Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
From: Apache Wiki <wikidiffs@apache.org>
To: Apache Wiki <wikidiffs@apache.org>
Date: Fri, 04 Dec 2009 06:02:32 -0000
Message-ID: <20091204060232.2017.15195@eos.apache.org>
Subject: 
 =?utf-8?q?=5BCouchdb_Wiki=5D_Update_of_=22Generating_HTML_from_Javascript?=
 =?utf-8?q?_shows_and_lists=22_by_RogerBinns?=

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for c=
hange notification.

The "Generating HTML from Javascript shows and lists" page has been changed=
 by RogerBinns.
The comment on this change is: Info about Javascript templating.
http://wiki.apache.org/couchdb/Generating%20HTML%20from%20Javascript%20show=
s%20and%20lists

--------------------------------------------------

New page:
=3D Generating HTML from Javascript shows and lists =3D
You can generate output from [[http://books.couchdb.org/relax/design-docume=
nts/shows|shows]] and [[http://books.couchdb.org/relax/design-documents/lis=
ts|lists]].  Typically this would be HTML intended for a browser but any fo=
rmat can be generated. CouchDB already includes [[http://en.wikipedia.org/w=
iki/ECMAScript_for_XML|Javascript support]] for XML derived formats (eg Ato=
m feeds). It is impractical to generate HTML directly so some sort of templ=
ating is recommended.

=3D=3D Best Practise =3D=3D
Generate clear concise simple HTML from your show/list functions.  The resu=
lting HTML interface should be usable from constrained devices (eg cell pho=
nes, set top boxes) as well as being accessible (eg for screen readers for =
blind people) and easy to index for search engines.  This is also easier to=
 automatically test.  You can then run Javascript in the browser (if the br=
owser supports Javascript and it is turned on) to enhance what is being dis=
played (eg add extra information, tooltips, icons, previews of next/previou=
s content, enhanced menus and interaction etc).

=3D=3D Constraints =3D=3D
The Javascript view server and the environment the code run in mean that so=
me existing Javascript templating libraries will not work.

 * There is no network/file access so templates cannot be loaded over the n=
etwork or from a file.  Instead they must be strings already included into =
your Javascript code.  (See the !json directive of couchapp which does this=
 for you).  They must also return strings.
 * There is no [[http://en.wikipedia.org/wiki/Document_Object_Model|DOM]] a=
vailable (templating libraries often assume that they are running in a brow=
ser working on the currently displayed document)
 * Some work on complete documents whereas your show and especially list fu=
nctions are often working on multiple strings and template fragments
 * Some only do HTML - this is good if they ensure the result is correct HT=
ML
 * Some do any form of templating (eg plain text) which means your resultin=
g HTML can be invalid
 * It is a very good idea to use a library that automatically escapes value=
s (eg replacing < with ampersand lt semicolon) otherwise your application w=
ill be prone to [[http://en.wikipedia.org/wiki/Cross-site_scripting|cross s=
ite scripting attacks]].  It should also provide a way of disabling the esc=
aping when you are intentionally providing raw HTML.
 * Size can be a problem.  Some templating libraries are rather large and d=
epend on other libraries. They can create many layersof intermediary functi=
ons and caching making it hard to debug what is happening.

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

=3D=3D=3D John Resig's micro-templating =3D=3D=3D
This engine is a screenful of code and can be downloaded at http://ejohn.or=
g/blog/javascript-micro-templating.  You can read about using it in the [[h=
ttp://books.couchdb.org/relax/design-documents/shows#Using%20Templates|Couc=
hDB book]].  Example usage can be found in the [[http://github.com/jchris/s=
ofa|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 genera=
te 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
<% } %>
}}}