Skip to content
Browse files

Added a very simple example, and re-titled to match the goal, not the

means.

The developer's perspective is "I know what page I want the user to see.
How do I make that happen with couchdb?".  The answer is to organize the
data in a view function, and then write a list function which will do the content-type
specific parts, such as generate HTML.  This page presumed the user already
knew that they needed to transform a view to get content, and was
already thinking from that perspective.  I hope my addition at the top
brings them across, before delving into details.
  • Loading branch information...
1 parent 4695397 commit 1e96e6d2a2c8457d3dae8a1db5386fa8a68ffbe1 @sakoht sakoht committed
Showing with 41 additions and 4 deletions.
  1. +41 −4 draft/transforming.html
View
45 draft/transforming.html
@@ -1,4 +1,4 @@
-<title>Transforming Views with List Functions</title>
+<title>Rendering Content Based-On Multiple Documents with List Functions</title>
<meta charset="utf-8">
@@ -10,16 +10,53 @@
<script src="../script.js"></script>
-<h2 id="transforming">Transforming Views with List Functions</h2>
+<h2 id="transforming">Rendering Content Based-On Multiple Documents with List Functions</h2>
-<p>Just as show functions convert documents to arbitrary output formats, CouchDB <em>list functions</em> allow you to render the output of view queries in any format. The powerful iterator API allows for flexibility to filter and aggregate rows on the fly, as well as output raw transformations for an easy way to make Atom feeds, HTML lists, CSV files, config files, or even just modified JSON.
+<p>Just as <em>show functions</em> convert an <strong>individual</strong> document into an arbitrary output format, CouchDB <em>list functions</em> are used to render documents as a <strong>group</strong>.
+
+<p>A list function is invoked with a URL specifying both the list function name and also the underlying view which will provide and organize the data.
+
+<p>For example, given this simple view, which indexes documents by "user_id":
+<pre>
+http://mysite/mydb/_design/myapp/_view/mydocs-by-user
+</pre>
+<pre>
+function(doc) {
+ if (doc.user_id) {
+ emit(doc.user_id, null);
+ }
+};
+</pre>
+
+
+<p>
+This list function renders the list of users in a simple HTML page:
+<pre>
+http://mysite/mydb/_design/myapp/_list/mylist/mydocs-by-user
+</pre>
+<pre>
+function(doc, req) {
+ provides("html", function() {
+ html = "&lthtml&gt&ltbody&gt&ltol&gt\n";
+ while (row = getRow()) {
+ html += "&ltli&gt" + row.key + ":" + row.value + "&lt/li&gt\n";
+ }
+ html += "&lt/ol&gt&lt/body&gt&lt/head&gt";
+ return html;
+ });
+}
+</pre>
+
+<p>Note that a list function can be used with a variety of views, or might be tailored to produce an elaborate page from a view designed specifically to organize data for it.
+
+<p>The powerful iterator API allows for flexibility to filter and aggregate rows on the fly, as well as output raw transformations for an easy way to make Atom feeds, HTML lists, CSV files, config files, or even just modified JSON.
<p>List functions are stored under the <code>lists</code> field of a design document. Here’s an example design document that contains two list functions:
<pre>
{
"_id" : "_design/foo",
- "_rev" : "1-67at7bg",
+ "_rev" : "1-67aGt7bg",
"lists" : {
"bar" : "function(head, req) { var row; while (row = getRow()) { ... } }",
"zoom" : "function() { return 'zoom!' }",

0 comments on commit 1e96e6d

Please sign in to comment.
Something went wrong with that request. Please try again.