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 StuartLangridge. The comment on this change is: add notes about etags and docless shows. http://wiki.apache.org/couchdb/Formatting_with_Show_and_List?action=diff&rev1=24&rev2=25 -------------------------------------------------- Since CouchDB 0.11.0 you can use the `send()` function as explained below in show functions as well. == Listing Views with CouchDB 0.10 and later == - List functions are stored under the `lists` key of a design document. Here's an example design doc with list functions, in addition to views: {{{#!highlight javascript @@ -100, +99 @@ }}} [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".] - An Example `list` function {{{#!highlight javascript @@ -116, +114 @@ } } }}} - == Listing Views with CouchDB 0.9 == - List functions were introduced in CouchDB 0.9 and had different, more complex API: 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: @@ -151, +147 @@ } } }}} - == Other Fun Things == === Stopping iteration in a `_list` === If you want to terminate iteration of a `_list` early you can return a `{stop: true}` JSON object from any of the calls to the function that include a row object. @@ -184, +179 @@ start({"code": 302, "headers": {"Location": "/"}}); } }}} - === Specifying Content-Type Response Header === 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: @@ -194, +188 @@ "body" : new XML('<xml><node foo="bar"/></xml>') } }}} - === 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. @@ -228, +221 @@ }}} 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 + === ETags === + The ETag for your _show will always be the ETag of the underlying document. This means that if you sneakily try to provide dynamic content by doing things in your _show function, a browser will not refresh the page if the dynamic content changes; a browser will pass an If-None-Match header with the ETag from the previous time it called your _show, and CouchDB will return the same ETag (because the underlying document has not changed) ''even if the dynamic content you added has changed'', and a 304 Not Modified header. + + You can circumvent this, sort of. The things that go into calculating the ETag for a _show URL are: the ETag of the underlying document, the requesting user-agent's Accept header, and the currently logged-in user's roles. So, if the thing you want to alter in the dynamic content is a "user is logged in"/"user is not logged in" header, make sure that your users have roles (it doesn't matter what they are); this will ensure that a logged-in user and a non-logged-in user will get different ETags for the same _show function on the same document. + + === Shows without a document === + Technically, you do not have to pass a docid at all. You can just + + {{{ + GET /db/_design/examples/_show/haha + }}} + to run the "haha" _show without any document at all. This can be a nice way of getting some server-side processing done; your "haha" show function might return the contents of a template, for example, and alter the content based on the current userCtx. Be sure and read the point above about ETags, though. +
