Couch Book Progress
It’s been a few weeks since we released the initial chapters of O’Reilly’s CouchDB book. The next release ought to be happening “soon” – There’s more work to be done on it, but the major skeleton of the chapters has been written, and the figures drawn.
I’m posting the outline of the next section, so that people’s expectations about the book are inline with what we provide. The next released section will be a few chapters walking through the creation of a simple web app (yes, a weblog). The point is not to teach Ajax, but to teach the CouchDB HTTP API in a hands on way.
Yes, all the code runs, and the in-progress version of the example blog is even available on github. One of my main tasks between now and the release is to make the installation proceedure much easier. So you are welcome to play now, but if it seems messy or confusing, please try again when the chapters are released.
If anyone has input on pacing and ordering of the example application I’d love to hear it. I think this section should be relatively fast-paced, and focussed on how easy it is to build applications using CouchDB, with the occasional bits of API specification or deeper material presented as asides and sidebars.
2. Learning CouchDB
Touring the Futon Administration Interface
A survey of CouchDB’s http api, through the eyes of Futon. Touches on most of the core concepts. This material is might be better suited for Section 1, as it does stand alone as an introduction to the http API.
Introducing the Example Blog
Why we chose JavaScript for the book examples. Also: even if you are storing scientific data, what you’ll learn by following along is applicable (views, document semantics, design docs).
Setting Up Your Development Environment
Getting the example app to your local drive, and being able to push it to CouchDB. Also cover design-doc / application correspondence while explaining the couchapp script.
Storing Blog Posts in CouchDB
The JSON doc format, validation functions, plus the HTML and Javascript it takes to support the blog post form. (This will be a longer one, but the code for it shouldn’t be changing.)
Rendering Documents with CouchDB Forms
What forms are. Why they have the single-doc constraint. Mention that you can write raw JS, but then show CouchApp’s require / include system as a best practice, using templates and a basic templating engine.
Browsing Recent Posts with Map Views
Introduce a simple view by published at date. Show basics of pagination. Explain the view-query API by looking at the JavaScript client API used to query the view.
Mention that there will be forms for views in the future, so that this page can be served as HTML as well. (Forms for views should be in Couch 1.0 – and thus in the book, so polishing this section now is lower priority. Pagination will also be easier with view forms)
Accepting Reader Comments
The JSON format, validations, and the HTML form for updating a comment. This is a short one, mostly repeats what happened in “Storing Blog Posts in CouchDB” but its the second time, so we can touch on different aspects and explain other API details. (One neat difference is that we’re adding Javascript behavior to a page that was rendered as a CouchDB form, rather than a static document.)
Listing Related Comments Using View Collation and Compound Keys
(I didn’t say “joins”) ;)
Currently this uses an Ajax query that lists comments by [post_id, date]. When view forms are available, we’ll change it to Christopher Lenz’s query, which includes the post itself, so the whole thing can be rendered in a single request. This chapter works on the same files as the previous chapter, they could be “joined” but I think this is material we should take the space to cover as clearly as possible.
If you’ve gotten this far, then you must be seriously interested in CouchDB. If you are, then you should familiarize yourself with the test suite. It’s written in JavaScript, so anyone can understand it, and it’s the main gateway for new features. Plus, code speaks louder than words.