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 "Formatting_with_Show_and_List" by DavidAscher
Date Fri, 27 Nov 2009 04:22:32 GMT
Dear Wiki user,

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

The "Formatting_with_Show_and_List" page has been changed by DavidAscher.
The comment on this change is: Trying to be clearer about what the show and list APIs are
in 0.10.  Needs a full rewrite..
http://wiki.apache.org/couchdb/Formatting_with_Show_and_List?action=diff&rev1=18&rev2=19

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

- Note that this is only available in CouchDB 0.9 or newer — The API might still change.
+ == Compatibility notes ==
  
- The basics of formatting documents using `show` and `list` functions. These functions convert
documents and views, respectively, into non-JSON formats. The rows of each view are processed
individually, which keeps long lists from becoming memory hogs.
+ Show and list functions were introduced in CouchDB 0.9, and their APIs changed considerably
in 0.10.  There may be further changes in future versions.
  
- They are designed to be cacheable. CouchDB handles generating Etags for show and list responses.
+ == Introduction ==
  
+ The `show` and `list` functions are used to convert documents and views, respectively, into
non-JSON formats. `list` functions processed each row individually, which keeps long lists
from becoming memory hogs.  They are designed to be cacheable. CouchDB handles generating
Etags for show and list responses.
+ 
- Show and list functions are side effect free and idempotent. They can not make additional
HTTP requests against CouchDB. Their purpose is to render JSON documents in other formats.
+ Show and list functions are side effect free and idempotent. They can not make additional
HTTP requests against CouchDB. Their purpose is to render JSON documents in other formats,
such as HTML, Atom, XML, etc.
  
- == Showing Documents ==
+ == Showing Documents (`show` functions) ==
  
  Show functions are stored in your design document, under the `shows` key. Here's an example
set of show functions:
  
@@ -65, +67 @@

  
  
  The request and response objects are of the same format used by `_external` functions, as
documented in ExternalProcesses.
+ 
+ === `show` API in CouchDB 0.10 ===
+ 
+ In 0.10, the API available to `show` view has changed.  Instead of `respondWith`, use `provides`,
as follows:
+ 
+ {{{
+ function(doc, req) {
+ 
+   provides("html", function() {
+       return "<b>doc.title</b>";
+       });
+     }
+   );
+   provides("xml", function() {
+       return "<text class="title">doc.title</text>";
+       });
+     }
+   )
+ }
+ }}}
+ 
+ 
  
  == Listing Views with couchdb 0.9 ==
  
@@ -94, +118 @@

  GET /db/_design/examples/_list/browse-people/people-by-name?startkey=["a"]&limit=10
  }}}
  
- [As above, we assume the database is named "db" and the design doc "examples".]
+ In this example, the database is named "db", the design doc "examples", the list function
"browse-people" and the views are "posts-by-date", "posts-by-tag", etc.
  
  Couchdb 0.10 supports an alternate form of URL which allows you to use a list function and
a view from different design documents.  This is particularly useful when you want to use
a different language for the list and for the view.  These URLs are very similar to the above
examples, but instead of the tail portion being the name of the view, the tail portion can
consist of two parts - a design doc name and the name of the view in that second document.
 For example:
  
  {{{
  GET /db/_design/examples/_list/index-posts/other_ddoc/posts-by-tag?key="howto"
  }}}
- [As above, we assume the database is named "db" and the design doc with the list is named
"examples", while the design doc with the view is "other_ddoc".]
+ Here, the database is named "db", the design doc with the list is named "examples", the
list function is called "index-posts", and the view is "other_ddoc".
  
- A list function has a more interesting signature, as it is passed the head of the view on
first invocation, then each row in turn, then called one more time for the tail of the view.
The function should check the `head` and `row` parameters to identify which state it's being
called in; the sequence of calls to `listfn`, for a view with three rows, would look like:
+ [0.9]: A list function has a more interesting signature, as it is passed the head of the
view on first invocation, then each row in turn, then called one more time for the tail of
the view. The function should check the `head` and `row` parameters to identify which state
it's being called in; the sequence of calls to `listfn`, for a view with three rows, would
look like:
  
  {{{
    listfn(head, null,    req, null    );  // Before the first row: head is non-null
@@ -135, +159 @@

  }}}
  
  == Listing Views with couchdb 0.10 ==
- The list API has changed significantly from 0.9 to 0.10.
+ The list API has changed significantly from 0.9 to 0.10.  It is called once, but can output
bits of data using the `send` function, rather than accumulating everything in one return
value.  This allows chunking and higher performance.
  
+ 
- Example `list` function
+ A simple `list` function
  {{{
  function(head, req){
    var row;
@@ -147, +172 @@

  }
  }}}
  
+ The list function above assumes that the stock HTTP Response is correct.  If you are returning
anything other than JSON, however, it's not likely to be, so you should change the headers
using the `start()` call:
  
- == Other Fun Things ==
+ {{{
+   start({"headers":{"Content-Type" : "text/html"}});
+ }}}
+ 
+ See below for error codes and redirects as well.
  
  === Stopping iteration in a `_list` ===
  
@@ -185, +215 @@

  }
  }}}
  
- === Specifying Content-Type Response Header ===
+ === Specifying Content-Type Response Header [CouchDB 0.9] ===
  There are two ways to deal with a content-type header in the response to a show or list
request. The first way is to specify the content type as a member of the _show function's
response object:
  
  {{{
@@ -195, +225 @@

  }
  }}}
  
- 
- === Responding to different Content-Type Request Headers ===
  The second way to deal with content-type headers is to rely on some global helper
  methods defined by CouchDB's ''<couchdb>/server/main.js'' file. The ''registerType''
method lets you register a type key with
  one or more content-type strings. Please refer to the ''main.js'' file to see content-types
registered by default.
@@ -224, +252 @@

         });
  }}}
  
+ === Specifying Content-Type Response Header [CouchDB 0.10] ===
+ 
+ For `show` functions, as mentioned above, use 
+ {{{
+ start({"headers":{"Content-Type" : "text/html"}});
+ }}}
+ 
+ For `list` functions, use the `provide()` function to specify "html", "xml", etc.
+ 
+ 
+ === Example code ===
  
  Hopefully this is enough to get started. For a more complete set of examples, see the CouchDB
test suite, especially show_documents.js and list_views.js
  

Mime
View raw message