The first part of this tutorial was well received so I decided to continue and cover other parts of couchapp programming. 'couchapp' still means an evently web application pushed to a design document of CouchDB thanks to the couchapp python script.

You saw in the first part of the tutorial how to handle events, and communicate between widgets easily. This part is about 'state' in general, i.e.. how to push and retrieve data from evently widgets and the database.

$$(this)

You'll find out quickly that even if separating code in a widget by using several events, you often need to keep state between events. A good practice is to separate the business logic from the displaying logic, and $$(this) lets us do just that. Let me explain that with an example. I'm using the code from the first part, and would like to store multiple toppings, not only one (that's one of the exercises I proposed).

The first thing we'll be doing is to add an event to items, that I'll call addTopping. It will simply add an element to our list of items, and ask for the old 'topping' event to display this list. Our list will be an array of items stocked in $$(this). The first thing to do is to create the empty array. data.js in evently/items/_init is a perfect place for that.

$ cat data.js
function(e) {
  $$(this).toppings = [];
}

Whenever a new topping is asked, we have to add it to our array:

$ cat items/addTopping.js
function(e, topping) {
    $$(this).toppings.push({"top" : topping.slice(1)});
    $(this).trigger('topping');
}

We're pushing {"top": "cheese"} for example, so our array might look like this after a few clicks:

[{"top": "cheese"},{"top": "bacon"},{"top":"cheese"}]

The next step is to display this in mustache.

$ cat items/topping/mustache.html
<p>Toppings you'd like to see on your pizza:</p>
<ul>
{{#toppings}}
  <li>{{top}}</li>
{{/toppings}}
</ul>

This is a useful feature of mustache: displaying lists of things. Just start with {{#a_list}}, end with {{/a_list}}, and use the keys of your elements inside your list ("top" here). Keep in mind that mustache is designed to forbid logic in templates: there are no real loops, and in the couchapp version, no conditionals! If you need logic, just do it in js code.

There's a bit of plumbing left to do here. We have to evently.connect #sidebar and #items via addTopping, not topping, choices/_init/selectors/a/click.js should trigger addTopping, and data.js now returns {toppings: $$(this).toppings}, the key being the name of the list in our mustache.html file.

js state

Get tutorial-this-state.tar.gz if something went wrong for you.

Please try to add a link to delete all toppings, and a link associated to each topping to delete only this one (you'll probably have to use the array index). It's a good exercise to see if you've understood what you've just done.

Querying the database

Querying the database is just a matter of calling the right view or asking for the right document, and displaying the results via mustache. The great thing here is that there's no impedance mismatch! You don't need a complicated ORM to try and fit your js objects to your database objects: everything is JSON (remember part one?)!

How does it work? It's as simple as creating a query.js or query.json file. Let's start by inserting a few documents in our database with Futon (inserting documents via evently will be covered later). For example :

{
  "type": "topping",
  "contents": ["cheese", "bacon", "tomatoes"]
}

Once you've added two or three documents and worked out your view with the 'Temporary view' feature of Futon, type:

$ couchapp generate view toppings

This will create a 'toppings' folder in views/ with two file, map.js and reduce.js. You should remove reduce.js and fill map.js with the content of your temporary view. I came up with:

$ cat views/toppings/map.js
function(doc) {
  if(doc.type == "topping")
    emit(null, doc.contents);
}

I'll reuse the "#account" div and style from couchapp default app to display "some examples" of toppings to give ideas to our users. Modify "#profile" in the CSS to "#examples", and add an empty examples div: <div id="examples"><p>Some examples</p></div>. Note that the "some examples" text is just serving debugging purposes, but should not be left in production since it would cause an unpleasant blinking effect. Here is what we want to achieve:

query result

Alright, so what do we need in examples/_init?

query.json is only going to get the content from our toppings view, and get only two of them:

{
  "view": "toppings",
  "limit": "2"
}

data.js is going to simply give the rows of our view back to mustache:

function(data) {
  return {examples: data.rows};
}

This will return an array of arrays (if you want to know what is exactly returned, add $.log(data.rows); and look at your JS console).

[{"value" : [cheese, bacon, tomatoes]}, {"value": [tomatoes, bacon, eggs]}]

Now, there's only mustache.html left:

<p>A few examples that could inspire you:</p>
<ul>
{{#examples}}
  <li>{{value}}</li>
{{/examples}}
</ul>

There's a bit of magic involved in mustache here: it translates the js array ["cheese", "bacon", "tomatoes"] in a nice comma-separated text.

tutorial-query-db.tar.gz if something went wrong for you.

Anyways, this is it! Nothing more is needed to display data from your database. No ORM, no weird API, it's just JSON that you get from JavaScript! Isn't it relaxing? Of course, you can easily extend it:

Pushing to the database

I still don't know how to do that. :) You can always use $.ajax.

Try $$(this).app.db.saveDoc(my_doc, success_handler); (see evently/profile/profileReady/selectors/form/submit.js after couchapp generate).

What's next?

You already know a lot of things if you did experiment with my examples. You can continue to learn about evently by looking at the other documents from the Evently page, and look at the way the default account widget works: clever combinations between events to avoid coupling and have clear code. Read code from other applications, and write your own! Happy hacking!

Files attached to The 'Do It Yourself' Evently Tutorial - Part Two - State: