Fixes #36 - Add support for CouchDB lists

[kurtmilam]

If a list is specified in config.list_name or a collection's db.list attribute, the collection will be built based on the list.

If no list is specified, the collection is based on the specified view, as in the previous version.

[kurtmilam]

A note on implementation - your list function should return a stringified object containing a rows array. In short, the JSON returned by the list function should look similar to the JSON returned by a normal view.

Example list function:

function(head, req) {
    var row, obj = {rows:[]};
    while (row = getRow()){
        obj.rows.push(row);
    } 
    send(JSON.stringify(obj));
    //One Model per row in obj.rows will be added to the Collection
}

Also: If you wish to base a collection on a list, you should still supply a view name for the list to be executed against, just as you normally would when querying a CouchDB list.

Testing: I have tested the javascript version of this. I made the coffeescript changes by hand, but have not yet tested them. (haven't started working with coffeescript yet)

Why would I want to use a list rather than a view?
CouchDB lists offer access to environment variables and querystring params that are not available to views. This includes things like the userCtx (the user name of the user who's executing the query). Using a list, you can filter the records returned by the underlying view based on the user who's making the request, or based on other querystring params that you send with your call to the list.

Most of the documentation I've read about CouchDB lists talks about transforming a view's JSON into HTML, XML or some other format. What's often not mentioned is that you can also use a list to transform a view's JSON into JSON, as well - this is probably the most interesting use w/r/t Backbone.js apps.

Example list function that filters records based on the current user:

//This example assumes your docs have a top-level key called 'documentOwner' whose value matches 
//the 'name' key of one of the users defined in your '_users' database
function(head, req) {
    var row,
        obj = {rows:[]},
        currentUser = req.userCtx.name;
    while (row = getRow()){
        if (row.value.documentOwner === currentUser)
            obj.rows.push(row);
        }
    } 
    send(JSON.stringify(obj));
    //In this example, one model per doc where doc.documentOwner = the name of the current user
    //will be added to the collection
}

[kurtmilam]

The second commit is the correct one - it contains all of the changes from the first, plus an important if that I left out initially.

[janmonschke]

Thx for this addition, didn't know that you can use lists in that way :).
Can I take the text in your comment above and put it in the document at http://janmonschke.com/projects/backbone-couchdb.html ?

[kurtmilam]

Feel free to reuse my text, but I should add that I discussed this use of lists with some CouchDB experts on #couchdb, and they informed me that this should be used sparingly - only where it's impossible to get the same results with a view. The reason for this is that views are prepared beforehand, but lists must be built each time they're called.

In short, if you need JSON, use a view whenever possible, and only use a list when there's no way to get the same results with a view.