We have a new wiki. The migration is not 100% complete. You can help out by moving pages across. This wiki will exist for as long as there are pages left.

The official documentation has moved to http://docs.couchdb.org — The transition is not 100% complete, but http://docs.couchdb.org should be seen as having the latest info. In some cases, the wiki still has some more or older info on certain topics inside CouchDB.

You need to be added to the ContributorsGroup to edit the wiki. But don't worry! Just email any Mailing List or grab us on IRC and let us know your user name.

Generating HTML from Javascript shows and lists

You can generate output from shows and lists. Typically this would be HTML intended for a browser but any format can be generated. CouchDB already includes Javascript support for XML derived formats (eg Atom feeds). It is impractical to output HTML directly so some sort of templating is recommended.

As of the 0.11 release of CouchDB you can use CommonJS 1.0 modules in your show, list, update, and validation functions - see CommonJS_Modules.

Best Practise

Generate clear concise simple HTML from your show/list functions. The resulting HTML interface should be usable from constrained devices (eg cell phones, set top boxes) as well as being accessible (eg screen readers) and easy to index for search engines. This is also easier to automatically test. You can then run Javascript in the browser (if the browser supports Javascript and it is turned on) to enhance what is being displayed (eg add extra information, tooltips, icons, previews of next/previous content, enhanced menus and interaction etc).

It is a very good idea to use a library that automatically escapes values (eg replacing < with ampersand lt semicolon) otherwise your application will be prone to cross site scripting attacks. It should also provide a way of disabling the escaping when you are intentionally providing raw HTML.

It is convenient if the library has functions for emitting html. For example it may have a function to insert an image where you provide the URL and the function generates all the wrapping HTML, including width/height/caption attributes if you provided them.

You should avoid having code in your template. Some template libraries let you put any code you want between their tags. This is as bad an idea as putting HTML sprinkled throughout your code. It also makes the templates harder to translate (the translator has to understand the code) and is a maintenance burden (eg if you have similar code in multiple templates then they may all require changing for code updates). Instead you should be able to define a meaningfully named function that is part of the data supplied to the template.


The Javascript view server and the environment the code run in mean that some existing Javascript templating libraries will not work.


The solutions listed below are known to work with CouchDB show and list functions, generating HTML and working with CouchDB deployment conventions (ie !json string templates and !code inclusion into the show/list functions).

John Resig's micro-templating

This engine is a screenful of code described at http://ejohn.org/blog/javascript-micro-templating (download a CouchDB version here). You can read about using it in the CouchDB book. Example usage can be found in the Sofa blog application. It does not do HTML escaping so you will need to be very careful. The templating is not HTML specific so you can generate other formats. (The tags are HTML syntax though.)

This is an example of how to do conditionals:

<% if (o.foo) { %>
    Foo is true-ish
<% } else { %>
    Foo is not true-ish
<% } %>

Note that this library has no support, bug tracker or development/test/release process.


mustache.js is a Javascript version of a Ruby templating library. The name refers to the { and } characters looking like a mustache. Download http://github.com/janl/mustache.js/raw/master/mustache.js to get the latest version which drops right in using !json/!code as is.

The library is complete and does not put Javascript code into your template, but does have all the expected features (looping, conditionals etc). Although the intention is to generate HTML the templates are not HTML specific. The only exception is that substitutions by default are HTML escaped (use triple braces for no escaping). This is a very good thing.


Underscore is a small library of miscellaneous functions that also includes simple templating substantially similar to John Resig's micro templating above. The templating is not HTML specific and there is no automatic HTML escaping.


closure templates are a Google project used behind the scenes in places like gmail and Google docs. It is different from the other libraries in that the templates are compiled to Javascript code and you just include that Javascript code. This has the advantage that errors in your templates are detected at build time not run time. Values are automatically HTML escaped. In order for soyutils.js to work, you should include this line before including it:

var navigator={userAgent: ""};

Generating HTML from Javascript shows and lists (last edited 2012-04-21 06:57:24 by 151)