CouchApp: Standalone CouchDB Application Development Made Simple

CouchApp is designed to structure standalone CouchDB application development for maximum application portability.

CouchApp is a set of scripts and a jQuery plugin designed to bring clarity and order to the freedom of CouchDB's document-based approach.

Write apps using just JavaScript and HTML

Render HTML documents using JavaScript templates run by CouchDB. You'll get parallelism and cacheability, using only HTML and JS. Building standalone CouchDB applications according to correct principles affords you options not found on other platforms.

Deploy your apps to the client

CouchDB's replication means that programs running locally, can still be social. Applications control replication data-flows, so publishing messages and subscribing to other people is easy. Your users will see the benefits of the web without the hassle of requiring always-on connectivity.

Installation

easy_install couchapp

If this gives you trouble, see the INSTALLING file for more options, including the Ruby version of couchapp.

Begin Here

Once you run couchapp generate relax && cd relax, you're ready to get started. Views are found in the views directory, attachments are stored in the _attachments directory, forms functions are stored in list and show, and the generation script drops in additional explantory files.

There's more to Couch than this

CouchApp is by no means the only way to use CouchDB. CouchDB's technical roots make it well suited for very large installations. CouchDB excels at document management, archived stream processing (like logs or messaging), and other applications with voluminous data.

CouchApp concentrates instead on a more personal use case: developing and deploying standalone applications to CouchDB instances around the web.

It's the portability

There are apps you can build with server-side components that you can't build with just CouchApp. But by the same token, there are apps you can build on CouchApp alone that you can't build any other way. The flexibility of replication means that there are yet-undiscovered ways to mix datacenter level clusters with end-user installations.

Usage

To upload your application to a CouchDB database, run this command from within you application directory. In this example we assume you have a copy of CouchDB running on your local machine.

Push

couchapp push https://localhost:5984/mydb

You can use this url-form to send credentials data if you need to:

https://login:password@my.couchapp.com:5984/myapp

Push Helper Macros

CouchApp provides some neat helpers for getting code into your view and render functions. Look in the view files created by a generated app to see the usage for the !code and !json preprocessor macros. They are basically just two different ways to get more code into your functions.

!code for code

The !code path.to.code macro inserts the string value found at path.to.code of the design document, into the current file, at the position of the macro. Here's an example:

function(doc) {
  // !code lib.parser.html
  var parsed = new parseHTML(doc.html);
  emit(doc.key, parsed);
}

When you run couchapp push the !code line will be replaced with the contents of the file found at lib/parser/html.js. Simple as that.

As we begin to see more apps built using CouchApp, we plan to include helpful functions in the standard library (as supplied by couchapp generate). Thank you for helping us expand this section! :)

!json for data

After all the !code includes have been processed (insuring that included code may also use the !json macro), couchapp push does another pass through the function, running the !json path.to.json macros. This accumulates the data found in the JSON design doc at path.to.json into a single object for inclusion. After all the !json macros have been processed, the accumlated object is serialized to json and stored in variable names corresponding to their path's roots.

Here's an example. It's a lot of code to look at, but the principles are simple. Also, if you think you can explain it better than I have, please send a patch.

A Subset of the Design Doc Fields (for context)

{
  "lib" : {
    "templates" : {
      "post" : "<html> ... </html>",
      "comment" : "<html> ... </html>"
    },
    "render" : {
      "html" : "function(template, object){...}"
    }
  },
  "blog" : {
    "title" : "My Rad Blog"
  }
}

The Function

function(doc) {
  // !json lib.templates.post
  // !json blog.title  
  ...
  doSomething(lib.templates.post, blog.title);
}

The Result

function(doc) {
  var lib = {
    "templates" : {
      "post" : "<html> ... </html>"
    }
  };
  var blog = {
    "title" : "My Rad Blog"
  };
  ...
  doSomething(lib.templates.post, blog.title);
}

The upshot is that only the requested fields are included in the function. This allows you to put as many templates and libraries in your design doc as you wish, without creating overlong functions.

Silly Counter-example

function(doc) {
  // !json lib
  // !json lib.templates.post
}

In this example, the second usage of the macro is redundant, as the first usage will include the entire lib field as a JSON macro.

Deployment preferences in .couchapprc

You can set up application level helpers in the .couchapprc file

The format is like this:

{
  "env": { 
    "default": {
      "db": "https://user:pass@localhost:5984/myapp-dev"
    },
    "production": {
      "db": "https:///user:pass@example.com/myapp"
    }
  }
}

When you've setup .couchapprc you can push your app with just couchapp push or for non-default environments couchapp push production. This also has the advantage of not requiring password use on the command line. The .couchapprc file is not pushed with the rest of the design doc, but please be careful not to accidentally check your .couchapprc file into Git!

Clone

Clone downloads apps from other databases around the internet, all you have to do is point to the design doc url. Usage instructions will be here soon.

Community

There is a mailing list here: https://groups.google.com/group/couchapp

Also, join us on irc.freenode.net in the #couchapp room.

Apps Using CouchApp

There are a few apps out there already using CouchApp. Please send a pull request adding yours to the list if you're using it too.

• Sofa
• Couch-Wiki
• CouchDB Twitter Client

License

CouchApp is licensed under the Apache 2.0 License