Getting started

First, you'll need to include some new script tags on your pages:

<script src="underscore.js"></script>
<script src="jquery.js"></script>
<script src="jquery.couch.js"></script>
<script src="backbone.js"></script>
<script src="backbone.couchdb.js"></script>

Models

There's nothing that you'll need to do to make this work with models. The model id is going to be used to fetch/save the model and it will just work.

Collections

For collections, there's some extra configuration required:

Backbone.couch.Collection.extend({
    couch: function() {
        return {
            view: 'design/my_view'
        }
    },
    _db: Backbone.couch.db('my_database')
})

The couch function needs to return options to query the db with. In this example, The results of http://localhost:5984/my_database/_design/my_design_document/_view/my_view will be added to the collection (with each row being a separate model).

For a lot of views, it makes sense to have them look something like this:

emit(key, null);

This ends up saving disk space if you're just using the raw document (as it can be fetched with the include_docs query parameter). If you'd like to do this trick here:

{ view: 'design/my_view',
  include_docs: 'true'
}

Note that the couch function can return just about any query parameter. I find it especially useful for limiting the collection size and using startKey/endKey.

_changes

To get the changes feed working, you need to enable it in your model.

Backbone.couch.Collection.extend({
    change_feed: true
})

This is going to try and add everything on changes to your collection (which probably isn't the most desirable thing). To add filtering, so that the collection only sees updates for the specific thing it tracks, you can add a key to the couch() method.

Backbone.couch.Collection.extend({
    change_feed: true,
    couch: function() {
        return {
            filter: {
                filter: 'design/my_filter',
                /* query parameters */
                test: 'foobar'
            }
        }
    }
})

Update handlers

It is possible to use an update handler for all model create/updates. Just add the handler you'd like to use to the return value of couch():

Backbone.couch.Collection.extend({
    couch: function() {
        return {
            view: 'design/my_view',
            update: 'design/my_update'
        }
    }
})

Show handlers

If you'd like all the read calls to use a _show instead of the normal couch return for GET on documents. Like update handlers, you can just add the handler you'd like to use to the return value of couch():

Backbone.couch.Collection.extend({
    couch: function() {
        return {
            view: 'design/my_view',
            show: 'design/my_show'
        }
    }
})

List handlers

If you'd like your collections to use a _list instead of a _view, you can add the handler to couch():

Backbone.couch.Collection.extend({
    couch: function() {
        return {
            view: 'design/my_view',
            list: 'design/my_list'
        }
    }
})

Note that this will create an URL that looks like:

http://localhost:5984/mydb/_design/design/_list/my_list/my_view

TODOs

• Take some time to explain a little more of why this is useful.
• Do an example of the relationship between documents in the DB and models in the client.
• Add some couchapp steps to show the setup in couchapp itself.
• Show some more view options in the couch() method as examples.
• Move best practice suggestion for views to a footnote.