PEPBrowser: Next Evently Widget (Part II)

Resume Work on the 'pepstatuslist' Widget

Continuing from the previous blog post, lets start improving the 'pepstatuslist' widget. The previous blog post ended with the addition of the some code that enables the 'peplist' widget to trigger a 'setcategory' event when a category is chosen. Lets start adding the code that will listen to the 'setcategory' event.

Inside the 'pepstatuslist' folder, make a script file with the name, 'script.js'. The 'script.js' should contain the following code.

function (e, category) {

  $$(this).category = category;

  $(this).trigger('loadstatuslist');

}

The function in the code above is called when the 'pepstatuslist' widget receives a 'setcategory' event generated by the 'peplist' widget. The function accepts two arguments, the event object and the category value. The category value corresponds to the category clicked/tapped in the 'peplist' widget. The first statement of the function stores a name-value pair to the widget. This is done by the use of the $$ operator. The second statement of the function triggers a 'loadstatuslist' event.

loadstatuslist Handler

The 'loadstatuslist' event handler should load the list of document statuses under the chosen category. Since this event handler is not as simple as the 'setcategory' event handler, we need to make a folder for this event handler. So create a folder inside the 'pepstatuslist' folder with the name, 'loadstatuslist'. Inside the new folder add the javascript file, 'query.js'. The script file should contain the following code.

function () {

  var category = $$(this).category;

  return {

    view: "categorystatus",

    group_level: 2,

    "startkey": [category],

    "endkey": [category, {}]

  };

}

The 'query.js' file contains a function which returns a mapping of query parameters. Remember that in the '_init' event handler of the 'peplist' widget, it contains a 'query.json' file. The 'query.json' contains a mapping literal or JSON string that indicates the query parameters for the event handler. The 'query.json' file has the same purpose as the 'query.js' script. The reason why we use a script is that the query parameters is dynamic, it depends on the value of 'category' name-value pair assigned to the widget through the 'setcategory' event.

Honestly, the above mapping is not that simple and trying to explain it would take quite a long time. If you don't understand the mapping above, I advise you to consult the Views chapter of the "Definitive Guide to CouchDB".

Since, the other parts of the 'loadstatuslist' handler is quite similar to the '_init' handler of the 'peplist' widget. I'll just breeze through the other parts.

The code for 'data.js' follows.

function (data) {

  var l = [];

  for (var i=0; i < data.rows.length; i++) {

    l.push({'category': data.rows[i].key[0], 'status': data.rows[i].key[1], 'count': data.rows[i].value});

  }

  return {'statuslist': l};

};

The code in 'data.js' simply processes the data returned by the query. The function returns a mapping suitable for templating.

The Mustache template follows.

<ul id="pepstatuslist" data-role="listview" data-theme="c" data-dividertheme="b">

  {{#statuslist}}

  <li><a href="#pepdoclist" title="{{category}}|{{status}}">{{status}} ({{count}})</a></li>

  {{/statuslist}}

</ul>

The template simply displays the statuses in a clickable list. It is intended to be clickable so that the user can tap on a status and lead to a list of documents.

Finally, to activate the unordered list generated by the template above into a Jquerymobile list, the following code in 'after.js' is necessary to be executed.

function () {

$('#pepstatuslist').listview();

};

So far we have discussed the common pattern used for the rest of this application. I think that you would be able to understand the rest of the code available in the github repository.

PEPBrowser: Next Evently Widget (Part I)

Introduction

In my last post regarding the PEPBrowser project, we ended with a need for a new Evently widget. The Evently widget displays the PEP document statuses of the documents under the selected category and the number of documents for each status. I'm really not that great in explaining it with just words so lets try this example.

Illustrated above is what happens when the 'Process' item is selected. You could try it here.

Create 'categorystatus' View

Lets start creating this Evently widget by making a CouchDB View that will allow us to get a list of status under each category, with the number of documents for each status.

{"rows":[
{"key":["Informational","Active"],"value":12},
{"key":["Informational","Draft"],"value":4},
{"key":["Informational","Final"],"value":15},
{"key":["Informational","Rejected"],"value":3},
{"key":["Informational","Superseded"],"value":1},
{"key":["Informational","Withdrawn"],"value":3}
]}


{"rows":[
{"key":["Standards Track","Accepted"],"value":10},
{"key":["Standards Track","Deferred"],"value":17},
{"key":["Standards Track","Draft"],"value":20},
{"key":["Standards Track","Final"],"value":96},
{"key":["Standards Track","Rejected"],"value":57},
{"key":["Standards Track","Superseded"],"value":3},
{"key":["Standards Track","Withdrawn"],"value":15}
]}

Create a boileplate View using the 'couchapp' command-line tool.

$ couchapp generate view categorystatus

Remember that you have to run the above command inside the PEPBrowser app directory.

Running the command will create a 'categorystatus' directory, with map.js and reduce.js scripts inside. Modify the scripts as follows.

function(doc) {

  if (doc.type == 'pep') {

    emit([doc.category, doc.status], 1);

  }

}

The code for map.js is shown above.

function(keys, values, rereduce) {

  return sum(values);

}

The code reduce.js is shown above.

After modifying the map.js and reduce.js, you could now run 'couchapp push' and test the View.

http://[host]:[port]/pepbrowser/_design/pepbrowser/_view/categorystatus?group_level=2&startkey=['Standards Track']&endkey=['Standards Track', {}]

Start the pepstatuslist Widget

After setting up the CouchDB View, let us start making the 'pepstatuslist' widget. This widget would display a list of the status of documents under a category.

The first step in creating this widget would be to make a 'pepstatuslist' directory under the 'evently' directory. After creating the directory, we already have a widget that does nothing. But before making the widget functional, lets assign it first to a div container and make it receive events from the 'peplist' widget. The 'peplist' widget should be able to send it an event when the user taps on a category. To do this we modify the 'main.html' file inside the '_attachments' directory as follows.

<!doctype html>
<html>
<head>
  <title>PEP Browser</title>
  <link rel="stylesheet" href="style/jquery.mobile-1.0a4.1.min.css" type="text/css">
  <script src="js/myloader.js"></script>
  <script src="js/jquery.mobile-1.0a4.1.min.js"></script>
  <script type="text/javascript" charset="utf-8">
    $.couch.app(function(app) {
      $("#maincategorylist").evently("peplist", app);
      $("#maincategorystatuslist").evently("pepstatuslist", app);
      $.evently.connect("#maincategorylist","#maincategorystatuslist", ["setcategory"]);
    });
  </script>x
</head>
<body>
  <div data-role="page" id="categorylist">
    <div  data-role="header" data-theme="b">
      <h1>PEP Browser</h1>
    </div> 
<div  data-role="content">
 <div id="maincategorylist">
 </div>
</div> 
  </div>
  <div data-role="page" id="categorystatuslist">
    <div  data-role="header" data-theme="b">
      <h1>PEP Browser</h1>
    </div> 
<div  data-role="content">
 <div id="maincategorystatuslist">
 </div>
</div>
  </div>
</body>
</html>

The changes are highlighted in the code above. The first statement assigns the 'pepstatuslist' widget to the  div container with the 'id' of 'maincategorystatuslist'.  The second statement routes the 'setcategory' event from the 'peplist' widget to the 'pepstatuslist' widget.


$.evently.connect("#maincategorylist","#maincategorystatuslist", ["setcategory"]);


This means that everytime a 'setcategory' event is triggered inside the 'peplist' widget, the same event is sent to the 'pepstatuslist' widget. This enable the 'peplist' widget to send a message to the 'pepstatuslist' widget everytime a category is selected in the 'peplist' widget.

Back to the 'peplist' Widget

Before proceeding work with the 'pepstatuslist' widget, we go back to the 'peplist' widget. Why? Because in the previous section, we set the 'peplist' widget to communicate to the 'pepstatuslist' widget by routing the 'setcategory' event. So before proceeding work with the 'pepstatuslist' widget, lets add the code to 'peplist' to trigger the 'setcategory' event.

So back to the 'peplist' widget, we add the following folders and files under the '_init' folder.

These folders and file assign a click handler function to the link tags of the 'peplist' widget. Because the only links in the widget are links referring to a PEP doc category, all click events should load the proper category statuses in the 'pepstatuslist' widget and change the page to the 'categorystatuslist' page. The switching of the page is already finished in this blog post. To facilitate the loading of the category statuses, we put the following code to the 'click.js' file.

function () {

$(this).trigger('setcategory', [$(this).attr('title')]);

};

The code is so simple because it just triggers a 'setcategory' event and with the event sends the value of the 'title' attribute of the clicked link. The value of the 'title' attribute is the name of the category referred to by the link. This event is sent to the 'pepstatuslist' widget and the 'pepstatuslist' widget should update its contents according to the value passed with the event. The code for doing this would be made in the 'pepstatuslist' widget.

This blog post is becoming too long, I'll continue in another blog post. 

PEPBrowser: Lets Add Some Pages

Introduction

In the last post we create our first Evently widget which displays a list of PEP documents categories. Our intention here is that clicking/tapping on any of these items would bring us to a new page. The new page would be a list of PEP document status that is available under the chosen category. To implement this we need to make a new page, with a new Evently widget.

The Category Status Page

To create the new page, edit main.html in the _attachments folder.


<!doctype html>
<html>
<head>
  <title>PEP Browser</title>
  <link rel="stylesheet" href="style/jquery.mobile-1.0a4.1.min.css" type="text/css">
  <script src="js/myloader.js"></script>
  <script src="js/jquery.mobile-1.0a4.1.min.js"></script>
  <script type="text/javascript" charset="utf-8">
    $.couch.app(function(app) {
      $("#maincategorylist").evently("peplist", app);
    });
  </script>x
</head>
<body>
  <div data-role="page" id="categorylist">
    <div  data-role="header" data-theme="b">
      <h1>PEP Browser</h1>
    </div> 
<div  data-role="content">
 <div id="maincategorylist">
 </div>
</div> 
  </div>
  <div data-role="page" id="categorystatuslist">
    <div  data-role="header" data-theme="b">
      <h1>PEP Browser</h1>
    </div> 
<div  data-role="content">
 <div id="maincategorystatuslist">
 </div>
</div>
  </div>
</body>
</html>


Add the highlighted code above. The highlighted code serves as the new page. Notice that instead of  creating a new html file to represent the new page, we just added a 'div' tag. Yes we can use a separate html page for this, but this is easier because all the page switching is to handled by Jquerymobile. The attribute 'data-role="page"' indicates to Jquerymobile that the 'div' is a page. Not using a separate html page also has the advantage that it would be faster to load.

After the above changes, running 'couchapp push' and looking at the PEPBrowser application, one would notice that there are no noticeable changes. This because Jquerymobile hides the new page we added. By default, it displays the first div with the attribute 'data-role="page"' and hide the other pages. Tapping on one of the category entries would bring you to the new page we made. Why?

Switching Pages in Jquerymobile

Notice that we are able to switch to the new page we made from the main page of the PEPBrowser application. Why? Let's go back to the mustache template of the our first Evently widget.


<ul id="peplist" data-role="listview" data-theme="c" data-dividertheme="b">
  {{#categories}}
  <li><a href="#categorystatuslist" title="{{ key }}">{{key}} ({{value}})</a></li>
  {{/categories}}
</ul>

Highlighted above is the 'href' attribute of the link. It contains a link to an anchor, 'categorystatuslist'. But we do not have a 'categorystatuslist' anchor. We don't, but we have a div with an id of 'categorystatuslist', the new page we just added. This is how Jquerymobile handles anchor links. Easy page switching right!!!

The Need for another Evently Widget

Now,  the problem is that the new page does not display anything. We'll solve this by creating a new Evently widget that we will assign to the div inside our new page. I'll discuss this in my next blog post.

PEPBrowser: The First Evently Widget

Introduction

In this blog post, I will be walking you through on how I wrote the first Evently widget for the PEPBrowser App. The widget simply displays a listing of the main categories of the PEP documents. For those who would like to get the documents used for this project, simply replicate it from this CouchDB database, http://nieldomingo.iriscouch.com/pepbrowser/_design/pepbrowser/.

The PEP Document Represented in CouchDB

First and foremost, we have to understand the structure of the PEP doument stored in Couchdb. Below is an example of the PEP document as stored in Couchdb.


{
   "_id": "00808d5fefdabc7c068ed3089d08aac3",
   "_rev": "1-f4e2d53f17d1b8ff0842baf921f773b2",
   "category": "Process",
   "status": "Active",
   "num": "1",
   "version": "b5ab214ac135",
   "created": "13-Jun-2000",
   "url": "http://www.python.org/dev/peps/pep-0001",
   "lastmodified": "2011-03-04 05:03:26 +0000 (Fri, 04 Mar 2011)",
   "author": "Barry Warsaw, Jeremy Hylton, David Goodger",
   "html": "<div class=\"contents ...",
   "title": "PEP Purpose and Guidelines",
   "type": "pep"
}

The definition of the fields that we would be using follows.

• type - the document type. I used the value, 'pep', to identify the PEP document.
• category - the category of the PEP document.
• status - the status of the PEP document. It determines whether the PEP is accepted, rejected, active, etc.
• num - the number of the PEP document. PEP documents are numbered; they are usually referred as PEP 1, PEP 3000, etc.
• title - the title of the PEP.
• html - the html of the PEP document body.

The categories View

Before proceeding to writing the first Evently widget, we first need to make a CouchDB view that will generate a query of the information to be displayed by the widget. The widget would show a listing of all the PEP document categories and the number of documents for each category.

To start making this view, let us first generate some boiler-plate code using the couchapp utilty by running the following command.

couchapp generate view categories

The above command would generate a folder, named 'categories', inside the 'views' folder. Inside the 'categories' folder are two files, map.js and reduce.js. The map.js would contain the code for mapping part of the view and reduce.js would contain the code for the reduction part of the view.

The code for map.js follows.

function(doc) {

  if (doc.type == 'pep') {

    emit(doc.category, 1);

  }

}

The code for reduce.js follows.

function(keys, values, rereduce) {

  return sum(values);

}

The above view when run with a group_level=1 parameter, http://localhost:5984/pepbrowser/_design/pepbrowser/_view/categories?group_level=1, produces the following output.

{"rows":[
{"key":"Informational","value":38},
{"key":"Process","value":22},
{"key":"Standards Track","value":218}
]}

Categories List Evently Widget

Now that we have a CouchDB view, let us proceed with creating the evently widget. In the 'evently' folder of our Couchapp, create the folder, 'peplist'. 'peplist' would be the name of our widget. Inside the 'peplist' folder, create the folder '_init'. '_init' is the event that is triggered when the widget is loaded. This widget is intended to be part of the start page of the app so most of the work is done during initialization. Thus all our following activities in creating this widget is done inside the '_init' folder.

Inside the '_init' folder, create the query.json file. It should contain the following JSON.

{

  "view": "categories",

  "group_level": 1

}

The query.json file indicates the query to be done by the '_init' event. The 'view' field indicates the CouchDB view to be used and 'group_level' is a parameter to be used in making the query. The result of this query is passed to the function inside the 'data.js' function for processing.

Also under the '_init' folder, create the 'data.js' file with the following content.

function (data) {

return {'categories': data.rows};

};

The 'data' argument in the above function contains the result of the 'categories' view as defined by query.json. The above function is a simple function that returns a mapping to be used by the mustache template.

Create the mustache template inside the _init' folder. The filename of the mustache template should be 'mustache.html'. And for this case, it should contain the following markup.

<ul id="peplist" data-role="listview" data-theme="c" data-dividertheme="b">

  {{#categories}}

  <li><a href="#categorystatuslist" title="{{ key }}">{{key}} ({{value}})</a></li>

  {{/categories}}

</ul>

Notice in the above template that it lists down each and every row of the 'categories' field passed by the mapping of 'data.js'. Each row is represented by a list item tag, 'li', and a link tag, 'a'. The text contained in the link is the category name and the number of documents, i.e. "Informational (38)". The values of the 'href' and 'title' attributes contains values that will be explained later when we linked this widget to other widgets.

Lastly, we need to create the 'after.js' file with the following contents.

function () {

$('#peplist').listview();

};

The 'after.js' contains code that would be run  by the widget after all the other functions have been run, which explains its name. The function is necessary in order to initialize the list into a Jquerymobile list.

After all our changes, the peplist widget folder should look as follows.

Using the Evently Widget

To use the widget inside the main page of the app, we need to modify the 'main.html' file in the '_attachments' folder as follows.

<!doctype html>

<head>

  <title>PEP Browser</title>

  <link rel="stylesheet" href="style/jquery.mobile-1.0a4.1.min.css" type="text/css">

  <script src="js/myloader.js"></script>

  <script src="js/jquery.mobile-1.0a4.1.min.js"></script>

  <script type="text/javascript" charset="utf-8">

    $.couch.app(function(app) {

      $("#maincategorylist").evently("peplist", app);    

    });

  </script>

</head>

<body>

  <div data-role="page" id="categorylist">

    <div  data-role="header" data-theme="b">

      <h1>PEP Browser</h1>

    </div> 

<div  data-role="content">

 <div id="maincategorylist">

 </div>

</div> 

  </div>

</body>

</html>

The highlighted Javascript above connects the Evently widget we just created to the 'maincategorylist' div.

$("#maincategorylist").evently("peplist", app);

This means that the 'maincategorylist' div would contain the widget. It would display the markup generated by the widget.

After all of these changes, the app would look as follows.

PEPBrowser: Building the Base of the PEP Browser App

Introduction


In this blog post, I'll try to walk-through the process of making the base of the PEP Browser app. I'll be writing this from memory so I might miss some steps. So if you're trying to follow this and got lost, don't hesitate to leave me a comment.


Boilerplate Couchapp


To start, I made the initial boilerplate application using the Couchapp utility. You could install it using the following command in the command-line. (Note: my instructions assumes that you are using a unix based system)

$ sudo easy_install couchapp

After installing the Couchapp utility, I created the boilerplate application by running the following command.

$ couchapp generate pepbrowser

The above command would generate  a directory named, 'pepbrowser', which is a simple Couchapp which we will use as the starting for our project. Before starting to customize it, let us first push the initial Couchapp to a local Couchdb server to see that it works.

To push it to a Couchdb server, we need to modify or create the '.couchapprc' file inside the 'pepbrowser' folder. The file should look like as follows.

{
  "env": {
    "default": {
      "db": "http://username:password@localhost:5984/pepbrowser"
    }
  }
}

Remember that you should change the 'username' and  'password' in the above example. You should also change 'localhost' and '5984', in case your Couchdb server is not installed locally and does not use the default port.

After modifying the '.couchapprc' file, we push the initial Couchapp using the following command.

$ couchapp push

The above command should be run inside the 'pepbrowser' folder. Running the command would produce an output similar to the output below.

$ couchapp push
2011-06-22 21:53:45 [INFO] Visit your CouchApp here:
http://localhost:5984/pepbrowser/_design/pepbrowser/index.html

As indicated above, you could already visit the installed Couchapp using the link provided above. Visiting the above link in your browser wold display a page similar to the screen capture below.

By now, we have a working Couchapp. We will proceed with customizing the Couchapp.


Setup Initial View


As an initial page for this app, I want to setup a static html page with Jquerymobile working. I want to make sure that I could make Jquerymobile work inside a Couchapp. To start, I copied the 'index.html' file inside the '_attachments' directory to a new file 'main.html'. The 'main.html' is also located inside the '_attachments' folder. The 'main.html' page would be accessible through this url, http://localhost:5984/pepbrowser/_design/pepbrowser/main.html. But for this page to be accessible, you would have to run 'couchapp push' in order to push your changes to the server.


Before modifying the 'main.html' file, we would have to download and set-up the Jquerymobile files so that it could be loaded. I used Jquerymobile version 1.0a4.1 as I encountered some issues with the latest version. I'll try to update this later to the latest version if possible. Jquerymobile is composed of one javascript file, one CSS file and a folder of images. I copied the CSS file, 'jquery.mobile-1.0a4.1.min.css', to the 'style' directory inside the '_attachments' directory. I also copied to the 'style' directory the 'image' directory.

Inside the '_attachments' directory, I created a 'js' directory, which will contain javascript files. I placed inside that new directory the 'jquery.mobile-1.0a4.1.min.js' file. Now we have setup Jquerymobile inside our Couchapp.

One more thing. We need to add a newer version of Jquery to the 'js' directory. The reason for this is that the Couchapp comes with verion 1.4.2 which does not work with Jquerymobile 1.0a4.1. I tried upgrading to the latest version of Jquery, but it breaks Evently. After trying so many versions, the latest version of Jquery that works with both Evently and Jquerymobile 1.0a4.1 is version 1.4.4. So we get a minimized copy of that version and also place it inside the 'js' folder.

So now lets modify the 'main.html' file. It should now be similar to the following code.




<!doctype html>
<head>
  <title>PEP Browser</title>
  <link rel="stylesheet" href="style/jquery.mobile-1.0a4.1.min.css" type="text/css">
  <script src="js/myloader.js"></script>
</head>
<body>
  <div data-role="page">
    <div  data-role="header" data-theme="b">
      <h1>PEP Browser</h1>
    </div> 
<div  data-role="content">
 <div id="maincontent">
    <ul id="peplist" data-role="listview" data-theme="c" data-dividertheme="b">
 <li>
   <a href="#">Entry</a>
 </li>
 <li>
   <a href="#">Entry</a>
 </li>
 <li>
   <a href="#">Entry</a>
 </li>
 <li>
   <a href="#">Entry</a>
 </li>
 <li>
   <a href="#">Entry</a>
 </li>
</ul>
 </div>
</div> 
<div  data-role="footer" data-theme="b">
 <h1>Footer</h1>
</div>
  </div>
</body>
</html>





Notice some special tag attributes (data-role, data-theme) in the markup. This attributes are used by Jquerymobile. To better understand the above mark-up, check-out the Jquerymobile documentation. Its very easy to understand.


Another thing to notice in the code above is the link and script tag inside the header tag. The link tag is simply a reference to the Jquerymobile CSS located in the 'style' directory. The script tag refers to a custom javascript, myloader.js.


In the 'index.html' file in the '_attachments' directory, notice that it loads a javascript, 'loader.js'.



<!DOCTYPE html>
<html>
  <head>
    <title>My New CouchApp</title>
    <link rel="stylesheet" href="style/main.css" type="text/css">
  </head>
  <body>
    <div id="account"></div>


    <h1>Generated CouchApp</h1>


    <div id="profile"></div>
    <div id="items"></div>


    <div id="sidebar">
      <p>Edit welcome message.</p>
      <p>Ideas: You could easily turn this into a photo sharing app, or a grocery list, or a chat room.</p>
    </div>
  </body>
  <script src="vendor/couchapp/loader.js"></script>
  <script type="text/javascript" charset="utf-8">
    $.couch.app(function(app) {
      $("#account").evently("account", app);
      $("#profile").evently("profile", app);
      $.evently.connect("#account","#profile", ["loggedIn","loggedOut"]);
      $("#items").evently("items", app);
    });
  </script>
</html>



This script simply loads all the necessary Javascript files for the page to operate. Below is the code inside loader.js.

function couchapp_load(scripts) {

  for (var i=0; i < scripts.length; i++) {

    document.write('<script src="'+scripts[i]+'"><\/script>')

  };

};

couchapp_load([

  "/_utils/script/sha1.js",

  "/_utils/script/json2.js",

  "/_utils/script/jquery.js",

  "/_utils/script/jquery.couch.js",

  "vendor/couchapp/jquery.couch.app.js",

  "vendor/couchapp/jquery.couch.app.util.js",

  "vendor/couchapp/jquery.mustache.js",

  "vendor/couchapp/jquery.evently.js"

]);

Since we are loading some additional Javascript files and we would like to override the default Jquery version, I copied the contents of this loader.js into myloader.js and made some modifications. Its code resulting code of myloader.js follows.

function couchapp_load(scripts) {

  for (var i=0; i < scripts.length; i++) {

    document.write('<script src="'+scripts[i]+'"><\/script>')

  };

};

couchapp_load([

  "/_utils/script/sha1.js",

  "/_utils/script/json2.js",

  "js/jquery-1.4.4.min.js",

  "/_utils/script/jquery.couch.js",

  "vendor/couchapp/jquery.couch.app.js",

  "vendor/couchapp/jquery.couch.app.util.js",

  "vendor/couchapp/jquery.mustache.js",

  "vendor/couchapp/jquery.evently.js",

  "js/jquery.mobile-1.0a4.1.min.js"

]);

Note: I don't know if this is right, but I decided to put all script tags inside the <head> tag as i don't expect any loading delays as I plan to run this Couchapp in a local database, no network congestion. I might be wrong so feel free to leave a comment.


So now after all these changes to the boilerplate Couchap, we could push our changes to the Couchdb server using 'couchapp push' and view the 'main.html' page, http://localhost:5984/pepbrowser/_design/pepbrowser/main.html. The result when viewed in a regular browser would appear as follows.

Notice that the page looks to be more appropriate for a mobile browser.


Next Post


Next post, we will create an Evently widget for the listing of PEPs.

PEPBrowser: Introducing the Python PEP Browser

Introduction

Weeks ago I got interested in couchdb and also weeks ago a friend asks some advice regarding possible approaches in building a simple Android application, because of this I researched two topics, Couchdb and mobile application development. In my research, I discovered that this two topics intersect at some point, because Couchdb is being promoted in the mobile application domain through mobile Couchapps. This gave me an idea to combine my current research interests and develop a simple mobile Couchapp to further learn more about my current topics of interest.

As a simple project, I plan to develop a simple mobile app which lists down all Python Enhancement Proposals (PEPs), http://www.python.org/dev/peps/,  and allow the user to read each PEP. I chose this project as I found it useful from time to time to read PEPs to further understand Python language features. I doubt if this application would really be useful to anyone aside from me, but my intention is not to build a killer mobile app, but simply learn new software technologies.

Selected Software Technologies, Libraries, etc.

To implement this small project, I have chosen Couchdb to be the central technology. I plan to implement this project as a mobile Couchapp. In my research, I discovered that there are two ways of implementing Couchapps. One approach utilizes server-side scripts; this approach is discussed in chapters 10-14 of the book, "Couchdb: The Definitive Guide" (full text available at http://guide.couchdb.org/draft/index.html). Another approach utilizes client-side scripts; this approach uses the Evently Jquery plugin and is discussed in this page, http://couchapp.org/page/evently. I decided to use the client-side approach because I think its simpler than the server-side approach. Plus, I think that the main application of the server-side approach is for building web pages that should be friendly to search engines. Since this project is just a simple application which I intend to be served by a local mobile Couchdb server, it does not have to be friendly to search engine crawlers.

To easily create mobile application interfaces, I decided to use a mobile Javascript framework such as Jquerymobile, Sencha Touch, JQ Touch, etc. In the selection of which mobile Javascript  framework to use for this project,  I just went with my gut. I don't know why, but I felt most comfortable with using Jquerymobile. So for this project, I will use Jquerymobile for no clear reason.

Initial Research, Good Materials to Checkout to Understand the Technologies to be Used

Honestly, I got confused in my research on how to build Couchapps. This is because the book, "Couchdb: The Definitive Guide", discussed the use of server-side scripts in building Couchapps. Initially, I have decided to used the book, "Couchdb: The Definitive Guide", as my main reference. However, when I reached the chapters discussing how to create Couchapps I noticed that the book discussed a different approach than the one implemented in the latest version of the example application it used, https://github.com/jchris/sofa. I thought that the book was already outdated and the newer approach should be researched elsewhere. This lead me to the couchapp.org website, where I was able to learn about Evently and the Couchapps that primarily utilized client-side scripting.

It really took me sometime before I understood how to make Couchapps using Evently. I think this is because of the arrangement of the documentation in couchapp.org. Thus to help you get started with Couchapps and Evently faster, I have some suggestions.

1. First, read chapters 1-9 of "Couchdb: The Definitive Guide". This chapters discusses the basics of Couchdb. There are also chapters dealing with Couchapps, but if you decide to use Evently, I think those chapters won't be as much help.
2. Next, attentively watch and follow the Evently Guided Hackalong Screencast available through this url, http://www.youtube.com/watch?v=Xk5gaUURdJI. This would give you a jump start in learning how to use Evently and making Couchapps.
3. To further reinforce what you learned in the screencast, read and follow this tutorial, http://couchapp.org/page/evently-do-it-yourself, and its succeeding tutorial, http://couchapp.org/page/evently-do-it-yourself-ii-state.

Following the above steps would enable you to learn Couchdb and Couchapps faster and prepare you to follow my posts regarding this project.

What to Expect in My Next Post

I have been writing for about an hour now (it's quite tiring), I'll end my blog post now but I'll give you some appetizers on what to expect in my next blog post.

Below are some screenshots on what I have implemented so far. Its not much since I haven't given much time, but I think its already quite substantial as a skeleton for the application.

I have also made available the code through github, https://github.com/nieldomingo/pepbrowser.