couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Couchdb Wiki] Update of "Generating HTML from Javascript shows and lists" by RogerBinns
Date Fri, 04 Dec 2009 07:50:55 GMT
Dear Wiki user,

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

The "Generating HTML from Javascript shows and lists" page has been changed by RogerBinns.
The comment on this change is: Add mustache and underscore.
http://wiki.apache.org/couchdb/Generating%20HTML%20from%20Javascript%20shows%20and%20lists?action=diff&rev1=1&rev2=2

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

  You can generate output from [[http://books.couchdb.org/relax/design-documents/shows|shows]]
and [[http://books.couchdb.org/relax/design-documents/lists|lists]].  Typically this would
be HTML intended for a browser but any format can be generated. CouchDB already includes [[http://en.wikipedia.org/wiki/ECMAScript_for_XML|Javascript
support]] for XML derived formats (eg Atom feeds). It is impractical to generate HTML directly
so some sort of templating is recommended.
  
  == 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 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 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).
+ 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).
  
  == Constraints ==
  The Javascript view server and the environment the code run in mean that some existing Javascript
templating libraries will not work.
@@ -15, +15 @@

   * Some only do HTML - this is good if they ensure the result is correct HTML
   * Some do any form of templating (eg plain text) which means your resulting HTML can be
invalid
   * 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 [[http://en.wikipedia.org/wiki/Cross-site_scripting|cross
site scripting attacks]].  It should also provide a way of disabling the escaping when you
are intentionally providing raw HTML.
-  * Size can be a problem.  Some templating libraries are rather large and depend on other
libraries. They can create many layersof intermediary functions and caching making it hard
to debug what is happening.
+  * Size can be a problem.  Some templating libraries are rather large and depend on other
libraries. They can create many layers of intermediary functions and caching making it hard
to debug what is happening.
  
  == Solutions ==
  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).
  
+  . '''Recommendation: '''Use mustache.js
+ 
  === John Resig's micro-templating ===
- This engine is a screenful of code and can be downloaded at http://ejohn.org/blog/javascript-micro-templating.
 You can read about using it in the [[http://books.couchdb.org/relax/design-documents/shows#Using%20Templates|CouchDB
book]].  Example usage can be found in the [[http://github.com/jchris/sofa|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 engine is a screenful of code described at http://ejohn.org/blog/javascript-micro-templating
(download a CouchDB version [[http://github.com/jchris/sofa/raw/master/vendor/couchapp/template.js|here]]).
 You can read about using it in the [[http://books.couchdb.org/relax/design-documents/shows#Using%20Templates|CouchDB
book]].  Example usage can be found in the [[http://github.com/jchris/sofa|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:
  
@@ -32, +34 @@

      Foo is not true-ish
  <% } %>
  }}}
+ === mustache.js ===
+ [[http://github.com/janl/mustache.js|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 ===
+ [[http://documentcloud.github.com/underscore/|Underscore]] is a small library of miscellaneous
functions that also includes simple [[http://documentcloud.github.com/underscore/#template|templating]]
substantially similar to John Resig's micro templating above.  The templating is not HTML
specific and there is no automatic HTML escaping.
+ 

Mime
View raw message