browser-couch: tutorial.html comparison

comparison tutorial.html @ 95:86158b61b732 blog-post

Reworked the tutorial so that we don't have to have each snippet be a callback from the previous snippet, which makes the tutorial a lot harder to follow.

author	Atul Varma <varmaa@toolness.com>
date	Tue, 21 Apr 2009 12:13:18 -0700
parents	af36b00306d0
children

comparison

equal deleted inserted replaced

-:97820cdda26f
+:86158b61b732
 to have, and its API is not stable at all.</p>
 <p>Finally, a note about the code examples in this tutorial: they're
 actually being executed in your browser, and their output is sometimes
 being displayed in this tutorial too. While this helps ensure that the
-software is working as intended and also allows for some interactive
+software is working as intended and also allows for some <a
-learning opportunities, right now it also means that some parts of the
+class="intra-wiki" href="#try">interactive learning opportunities</a>,
-code examples may look a bit unusual. Furthermore, if you see any
+right now it also means that some parts of the code examples may look
-conspicuously blank areas in this tutorial, it could be because the
+a bit unusual. Furthermore, if you see any conspicuously blank areas
-tutorial code crashed&mdash;our apologies if this occurs.</p>
+in this tutorial, it could be because the tutorial code
+crashed&mdash;our apologies if this occurs.</p>
 <p>With that out of the way, let's get started.</p>
 <h1>Getting Started</h1>
 <p>Suppose we want to add offline support for a blog.  To get a
 database called <tt>blog-posts</tt> in BrowserCouch, you can use the
 following function:</p>
 <div class="example-code">
-BrowserCouch.get('blog-posts', onRetrieveCb, new FakeStorage());
+BrowserCouch.get('blog-posts',
+function onRetrieveCb(db) {
+blogDb = db; /* Save the DB for later. */ DONE();
+},
+new FakeStorage());
 </div>
 <p>It's clear that the first parameter is the name of the database we
 want; the second parameter is the callback that will be passed the
 database once it's fetched.</p>
 non-persistently in memory for the sake of example. We could just as
 easily leave out the third parameter to have BrowserCouch figure out
 the best storage backend based on our browser's capabilities.</p>
 <p>If the database doesn't already exist, an empty one will be created
-for us. Putting blog posts into the database can be done via
+for us. Putting blog posts into the database is done through the
-an <tt>onRetrieveCb()</tt> function like this:</p>
+<tt>put()</tt> method like so:</p>
 <div class="example-code">
-function onRetrieveCb(db) {
+blogDb.put(
-blogDb = db;
+[{id: 0, author: 'Myk', title: 'Burritos', content: 'Burritos are yum.'},
-blogDb.put(
+{id: 1, author: 'Thunder', title: 'Bacon', content: 'I like bacon.'},
-[{id: 0, author: 'Myk', title: 'Burritos', content: 'Burritos are yum.'},
+{id: 2, author: 'Thunder', title: 'Beer', content: 'Beer is good too.'}],
-{id: 1, author: 'Thunder', title: 'Bacon', content: 'I like bacon.'},
+function onDone() { /* Do stuff... */ DONE();}
-{id: 2, author: 'Thunder', title: 'Beer', content: 'Beer is good too.'}],
+);
-onPutCb
-);
-};
 </div>
 <p>Every item we put into our database needs to have an <tt>id</tt>
 attribute, but aside from that, the item can contain any
 JSON-encodable data.</p>
+<h1>Views</h1>
 <p>Now that we've put some data into our database, we can play around
 with generating views on the data using the <a
 href="http://en.wikipedia.org/wiki/MapReduce">MapReduce</a> mechanism.
 For instance, here's an ad-hoc view using only the map phase that
 organizes all the post titles by author:</p>
 <div class="example-code">
-function onPutCb() {
+blogDb.view({
-blogDb.view({
+map: function(doc, emit) {
-map: function(doc, emit) {
+emit(doc.author, doc.title);
-emit(doc.author, doc.title);
+},
-},
+finished: function(result) {
-finished: function(result) {
+displayInElement(result, 'author-keyed-view'); DONE();
-displayInElement(result, 'author-keyed-view');
+}
-tryAnotherView();
+});
-}
+</div>
-});
-}
+<p>The <tt>view()</tt> method above has lots of optional arguments,
-</div>
+which is why we're passing in a single object with keys corresponding
+to argument names. The <tt>map</tt> argument is the function to use
+for the map phase, and the <tt>finished</tt> argument is the callback
+to pass the view results into when processing is complete.</p>
 <p>The output placed in the <tt>author-keyed-view</tt> element is:</p>
 <div class="example-output" id="author-keyed-view"></div>
 arbitrary function called <tt>emit()</tt>.  The <tt>map()</tt>
 function then emitted key-value pairs which show up in the view. It's
 worth noting that <tt>map()</tt> can call <tt>emit()</tt> as much as
 it wants to; each call will add a new row to the view.</p>
-<p>We could also try creating another view that adds a
+<p>At this point you may want to jump to the <a class="intra-wiki"
-<tt>reduce()</tt> function to group together the blog post titles with
+href="#try">Try It For Yourself</a> section to play around with making
-the authors:</p>
+your own <tt>map()</tt> functions.</p>
-<div class="example-code">
+<p>The reduce phase of a view is totally optional and a little
-function tryAnotherView() {
+confusing. Let's try adding a <tt>reduce()</tt> function to our
-blogDb.view({
+earlier view to group together the blog post titles with the
-map: function(doc, emit) {
+authors:</p>
-emit(doc.author, doc.title);
-},
+<div class="example-code">
-reduce: function(keys, values) {
+blogDb.view({
-return values;
+map: function(doc, emit) {
-},
+emit(doc.author, doc.title);
-finished: function(result) {
+},
-displayInElement(result, 'author-titles-view');
+reduce: function(keys, values) {
-findRows(result);
+return values;
-}
+},
-});
+finished: function(result) {
-}
+authors = result; /* Save the result for later. */
+displayInElement(authors, 'author-titles-view'); DONE();
+}
+});
 </div>
 <p>The output is as follows:</p>
 <div class="example-output" id="author-titles-view"></div>
-<p>The <tt>reduce()</tt> mechanism is a bit harder to
+<p>Essentially, BrowserCouch takes all the rows generated by
-understand. Essentially, BrowserCouch takes all the rows generated by
 <tt>map()</tt> and generates a new list of key-value rows, where the
 value of each row is the list of all values that match the row's key.
 This explains what the <tt>values</tt> argument passed to
 <tt>reduce()</tt> is.</p>
 <p>Once you've got a view, you can use the view's <tt>findRow()</tt>
 method to find the first row whose key matches (or is closest to) the
 one you provide.  For example:</p>
 <div class="example-code">
-function findRows(result) {
+var rowIndex = authors.findRow('Thunder');
-var rowIndex = result.findRow('Thunder');
+displayInElement(authors.rows[rowIndex], 'author-find-row-view');
-displayInElement(result.rows[rowIndex], 'author-find-row-view');
-tryMyView();
-}
 </div>
 <p>The output for this one is:</p>
 <div class="example-output" id="author-find-row-view"></div>
-<h1>Now You Try!</h1>
+<a name="try"><h1>Try It For Yourself</h1></a>
 <p>If your eyes are crossed right now, no worries&mdash;most people
 take a long time to understand exactly what MapReduce is doing. That
 said, the easiest way to understand how MapReduce works is just to
 play around with creating your own view.</p>
 <p>You can use the text field below to do just that. Just press the
 tab key when you're done making changes to recompute the view.</p>
 <textarea class="example-code try-code">
-function tryMyView() {
+blogDb.view({
-blogDb.view({
+map: function(doc, emit) {
-map: function(doc, emit) {
+emit(doc.author, doc.title);
-emit(doc.author, doc.title);
+},
-},
+reduce: function(keys, values) {
-reduce: function(keys, values) {
+return values;
-return values;
+},
-},
+finished: function(result) {
-finished: function(result) {
+displayInElement(result, 'try-my-view'); DONE();
-displayInElement(result, 'try-my-view');
+}
-}
+});
-});
-}
 </textarea>
 <p>Here's the output to the above view:</p>
 <div class="example-output" id="try-my-view"></div>

Mercurial > browser-couch

comparison tutorial.html @ 95:86158b61b732 blog-post