Bradley Holt » HTML5

CouchApps at CouchConf NYC

Bradley Holt — Thu, 27 Oct 2011 20:05:52 +0000

Here are the slides from Monday’s CouchConf NYC session on CouchApps with CouchDB, JavaScript and HTML5:

CouchConf NYC CouchApps

View more presentations from Bradley Holt

CouchApps at jQuery Conference Boston 2011

Bradley Holt — Sun, 02 Oct 2011 17:15:51 +0000

Here are the slides from today’s jQuery Conference presentation on CouchApps with CouchDB & jQuery:

jQuery Conference Boston 2011 CouchApps

View more presentations from Bradley Holt

If you were in this talk, please give me feedback on SpeakerRate.

Speaking at CouchConf NYC

Bradley Holt — Thu, 29 Sep 2011 16:33:58 +0000

I’m pleased to announce that I’ll be speaking at CouchConf New York City on October 24, 2011. This event is part of the CouchConf World Tour presented by Couchbase. My talk will be on CouchApps with CouchDB, JavaScript and HTML5. From the talk description:

In this talk we’ll see how to build CouchApps using CouchDB, Javascript, and HTML5. We’ll look at related tools such as the couchapp command ine tool, the Evently jQuery plugin, the CouchDB API jQuery plugin, the CouchApp Loader, Pathbinder, and the Mustache templating framework.

CouchApps at OSCON 2011

Bradley Holt — Wed, 27 Jul 2011 23:30:23 +0000

Here are the slides from today’s OSCON presentation on CouchApps with CouchDB, JavaScript & HTML5:

OSCON 2011 CouchApps

View more presentations from Bradley Holt

CouchDB jQuery Plugin Reference

Bradley Holt — Thu, 14 Jul 2011 22:18:46 +0000

I’ve had a difficult time finding documentation on the CouchDB jQuery plugin that ships with CouchDB. So, I’ve decided to create my own reference and share it with you. This should cover almost the entire CouchDB API that is available through the version of the plugin that ships with CouchDB 1.1.0.

Setup

The same-origin policy effectively requires that the HTML from which the JavaScript is loaded must be served up from CouchDB (you could instead use a reverse proxy server). This can be done by attaching an HTML document to a CouchDB document. You can do this manually, or through the use of CouchApps.

CouchDB ships with several useful JavaScript libraries, including jQuery. Here is an example of an HTML document that takes advantage of CouchDB’s included JavaScript libraries:



  
    CouchDB jQuery Examples

By default, CouchDB will use an empty string as its URL prefix. However, you can configure this before your first API call. For example:

$.couch.urlPrefix = "http://localhost:5984";

You will typically not want to change this value since the same-origin policy prevents you from accessing CouchDB databases hosted at a different origin.

Server API

Server Information

JavaScript example:

$.couch.info({
    success: function(data) {
        console.log(data);
    }
});

Resulting HTTP request:

GET http://localhost:5984/ 200 OK

Console output:

{
    "couchdb"="Welcome",
    "version"="1.1.0"
}

All DBs

JavaScript example:

$.couch.allDbs({
    success: function(data) {
        console.log(data);
    }
});

Resulting HTTP request:

GET http://localhost:5984/_all_dbs 200 OK

Console output:

[
    "_replicator",
    "_users"
]

User Signup

JavaScript example:

var userDoc = {
    _id: "org.couchdb.user:bob",
    name: "bob"
};
$.couch.signup(userDoc, "supersecurepassword", {
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
});

Resulting HTTP request:

PUT http://localhost:5984/_users/org.couchdb.user%3Abob 201 Created

Console output:

{
    "ok"=true,
    "id"="org.couchdb.user:bob",
    "rev"="1-230dc0625bd3c4aac735846cc152c296"
}

Login

JavaScript example:

$.couch.login({
    name: "bob",
    password: "supersecurepassword",
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
});

Resulting HTTP request:

POST http://localhost:5984/_session 200 OK

Console output:

{
    "ok":true,
    "name":"bob",
    "roles":[]
}

This will result in an AuthSession cookie being set and then sent back to the server on subsequent requests, authenticating the user on each request. The session length is 10 minutes by default, but can be set in CouchDB’s couch_httpd_auth.timeout configuration option.

Session

JavaScript example:

$.couch.session({
    success: function(data) {
        console.log(data);
    }
});

Resulting HTTP request:

GET http://localhost:5984/_session 200 OK

Console output:

{
    "ok":true,
    "userCtx":{
        "name":"bob",
         "roles":[]
    },
    "info":{
        "authentication_db":"_users",
        "authentication_handlers":[
            "oauth",
            "cookie",
            "default"
        ],
        "authenticated":"cookie"
    }
}

Logout

JavaScript example:

$.couch.logout({
    success: function(data) {
        console.log(data);
    }
});

Resulting HTTP request:

DELETE http://_:_@localhost:5984/_session 200 OK

Console output:

{
    "ok":true
}

This will set the AuthSession cookie to an empty string, effectively logging the client out.

Active Tasks

JavaScript example:

$.couch.activeTasks({
    success: function(data) {
        console.log(data);
    }
});

Resulting HTTP request:

GET http://localhost:5984/_active_tasks 200 OK

Console output:

[]

Server Configuration

JavaScript example:

$.couch.config({
    success: function(data) {
        console.log(data);
    }
}, "uuids", "algorithm");

Resulting HTTP request:

GET http://localhost:5984/_config/uuids/algorithm 200 OK

Console output:

"sequential"

The second and third parameters are the section and option parameters, respectively. Omit the option parameter if you’d like to retrieve the entire section. Omit both the section and option parameters if you’d like to see the entire server configuration. Add an optional fourth parameter to set the configuration option’s value, which will result in a PUT request with the value.

User DB

JavaScript example:

$.couch.userDb(function(data) {
    console.log(data);
});

Resulting HTTP request:

GET http://localhost:5984/_session 200 OK

Console output:

{
    "name"="_users",
    "uri"="../_users/"
}

The URI will be relative to the HTML executing the script.

New UUID

JavaScript example:

var uuid = $.couch.newUUID();
console.log(uuid);

Resulting HTTP request:

GET http://localhost:5984/_uuids?count=1 200 OK

Console output:

d12ee5ea1df6baa2b06451f44a0156fa

This function takes a count parameter as an optional first parameter. If the count parameter is greater than one, then it will keep a cache of UUIDs that will be returned on subsequent calls, rather than making another request to the server.

Replicate

JavaScript example:

$.couch.replicate("mydb", "otherdb", {
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
}, {
    create_target: true
});

Resulting HTTP request:

POST http://localhost:5984/_replicate 200 OK

Console output:

{
    "ok":true,
    "session_id":"705797bae87456c52f5b76f44fe5f245",
    "source_last_seq":27,
    "replication_id_version":2,
    "history":[
        {
            "session_id":"705797bae87456c52f5b76f44fe5f245",
            "start_time":"Wed, 13 Jul 2011 22:40:09 GMT",
            "end_time":"Wed, 13 Jul 2011 22:40:09 GMT",
            "start_last_seq":0,
            "end_last_seq":27,
            "recorded_seq":27,
            "missing_checked":0,
            "missing_found":14,
            "docs_read":14,
            "docs_written":14,
            "doc_write_failures":0
        }
    ]
}

Database API

Create Database

JavaScript example:

$.couch.db("mydb").create({
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
});

Resulting HTTP request:

PUT http://localhost:5984/mydb/ 201 Created

Console output:

{
    "ok":true
}

Database Info

JavaScript example:

$.couch.db("mydb").info({
    success: function(data) {
        console.log(data);
    }
});

Resulting HTTP request:

GET http://localhost:5984/mydb/ 200 OK

Console output:

{
    "db_name":"mydb",
    "doc_count":0,
    "doc_del_count":0,
    "update_seq":0,
    "purge_seq":0,
    "compact_running":false,
    "disk_size":79,
    "instance_start_time":"1310597000825187",
    "disk_format_version":5,
    "committed_update_seq":0
}

Save New Document

JavaScript example:

var doc = {};
$.couch.db("mydb").saveDoc(doc, {
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
});

Resulting HTTP request:

POST http://localhost:5984/mydb/ 201 Created

Console output:

{
    "ok":true,
    "id":"d12ee5ea1df6baa2b06451f44a019ab9",
    "rev":"1-967a00dff5e02add41819138abb3284d"
}

Open Document

JavaScript example:

$.couch.db("mydb").openDoc("d12ee5ea1df6baa2b06451f44a019ab9", {
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
});

Resulting HTTP request:

GET http://localhost:5984/mydb/d12ee5ea1df6baa2b06451f44a019ab9 200 OK

Console output:

{
    "_id":"d12ee5ea1df6baa2b06451f44a019ab9",
    "_rev":"1-967a00dff5e02add41819138abb3284d"
}

Note that the HTTP response includes an Etag HTTP header. If you do a subsequent request for the same document, and your client supports caching and conditional HTTP requests, then an If-None-Match header should be sent using the value from the previous response’s Etag header. If the document has not been modified, then CouchDB will send a 304 Not Modified response and no response body, saving bandwidth and speeding up the response.

Save Updated Document

JavaScript example:

var doc = {
    _id: "d12ee5ea1df6baa2b06451f44a019ab9",
    _rev: "1-967a00dff5e02add41819138abb3284d",
    foo: "bar"
};
$.couch.db("mydb").saveDoc(doc, {
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
});

Resulting HTTP request:

PUT http://localhost:5984/mydb/d12ee5ea1df6baa2b06451f44a019ab9 201 Created

Console output:

{
    "ok":true,
    "id":"d12ee5ea1df6baa2b06451f44a019ab9",
    "rev":"2-13839535feb250d3d8290998b8af17c3"
}

Remove Document

JavaScript example:

var doc = {
    _id: "d12ee5ea1df6baa2b06451f44a019ab9",
    _rev: "2-13839535feb250d3d8290998b8af17c3"
};
$.couch.db("mydb").removeDoc(doc, {
     success: function(data) {
         console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
});

Resulting HTTP request:

DELETE http://localhost:5984/mydb/d12ee5ea1df6baa2b06451f44a019ab9?rev=2-13839535… 200 OK

Console output:

{
    "id":d12ee5ea1df6baa2b06451f44a019ab9
    "ok":true,
    "rev":"3-1f04f977685e1108b4664f70b09c6f65"
}

Bulk Save

JavaScript example:

$.couch.db("mydb").bulkSave({"docs": [{}, {}]}, {
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
});

Resulting HTTP request:

POST http://localhost:5984/mydb/_bulk_docs?successStatus=201 201 Created

Console output:

[
    {
        "id":"d12ee5ea1df6baa2b06451f44a01a0d8",
        "rev":"1-967a00dff5e02add41819138abb3284d"
    },
    {
        "id":"d12ee5ea1df6baa2b06451f44a01a75a",
        "rev":"1-967a00dff5e02add41819138abb3284d"
    }
]

Bulk Remove

JavaScript example:

var docs = [
    {
        _id: "d12ee5ea1df6baa2b06451f44a01a0d8",
        _rev: "1-967a00dff5e02add41819138abb3284d"
    },
    {
        _id: "d12ee5ea1df6baa2b06451f44a01a75a",
        _rev: "1-967a00dff5e02add41819138abb3284d"
    }
];
$.couch.db("mydb").bulkRemove({"docs": docs}, {
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
});

Resulting HTTP request:

POST http://localhost:5984/mydb/_bulk_docs?successStatus=201 201 Created

Console output:

[
    {
        "id":"d12ee5ea1df6baa2b06451f44a01a0d8",
        "rev":"2-eec205a9d413992850a6e32678485900"
    },
    {
        "id":"d12ee5ea1df6baa2b06451f44a01a75a",
        "rev":"2-eec205a9d413992850a6e32678485900"
    }
]

This operates almost exactly like the bulk save, but instead sets the deleted flag to true on the documents.

All Documents

JavaScript example:

$.couch.db("mydb").allDocs({
    success: function(data) {
        console.log(data);
    }
});

Resulting HTTP request:

GET http://localhost:5984/mydb/_all_docs 200 OK

Console output:

{
    "total_rows":11,
    "offset":0,
    "rows":[
        {
            "id":"_design/default",
            "key":"_design/default",
            "value":{
                "rev":"9-5212dde9da06f1933dbe29811fc380d4"
            }
        },
        {
            "id":"d12ee5ea1df6baa2b06451f44a002cef",
            "key":"d12ee5ea1df6baa2b06451f44a002cef",
            "value":{
                "rev":"1-967a00dff5e02add41819138abb3284d"
            }
        },
        …
    ]
}

All Design Documents

JavaScript example:

$.couch.db("mydb").allDesignDocs({
    success: function(data) {
        console.log(data);
    }
});

Resulting HTTP request:

GET 
http://localhost:5984/mydb/_all_docs?startkey=%22_design%22&endkey=%22_design0%22 200 OK

Console output:

{
    "total_rows":11,
    "offset":0,
    "rows":[
        {
            "id":"_design/default",
            "key":"_design/default",
            "value":{
                "rev":"9-5212dde9da06f1933dbe29811fc380d4"
            }
        }
    ]
}

All Apps

JavaScript example:

$.couch.db("tutorial").allApps({
    success: function(data) {
        console.log(data);
    },
    eachApp: function(appName, appPath, ddoc) {
        console.log(appName);
        console.log(appPath);
        console.log(ddoc);
    }
});

Resulting HTTP requests:

GET http://localhost:5984/tutorial/_all_docs?startkey=%22_design%22&endkey=%22_design0%22 200 OK

GET http://localhost:5984/tutorial/_design/tutorial 200 OK

Console output:

tutorial

/tutorial/_design/tutorial/index.html

{
    "_id":"_design/tutorial",
    "_rev":"5-276897ecff6dc272c0b9143aa23e8a2e",
    …
}

This is intended as a convenience to find metadata about CouchApps.

Query

JavaScript example:

var mapFunction = function(doc) {
    emit();
};
$.couch.db("mydb").query(mapFunction, "_count", "javascript", {
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    },
    reduce: false
});

Resulting HTTP request:

POST http://localhost:5984/mydb/_temp_view?reduce=false 200 OK

Console output:

{
    "total_rows":10,
    "offset":0,
    "rows":[
        {
            "id":"d12ee5ea1df6baa2b06451f44a002cef",
            "key":null,
            "value":null
        },
        {
            "id":"d12ee5ea1df6baa2b06451f44a0037b5",
            "key":null,
            "value":null
        },
        {
            "id":"d12ee5ea1df6baa2b06451f44a003b06",
            "key":null,
            "value":null
        },
        …
    ]
}

This creates a temporary view as defined by your map and reduce functions. Temporary views are useful in development, but should be replaced with views permanently saved to design documents for production. Temporary views are slow, especially with a large number of documents.

View

JavaScript example:

$.couch.db("mydb").view("default/all", {
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    },
    reduce: false
});

Resulting HTTP request:

GET http://localhost:5984/mydb/_design/default/_view/all?reduce=false 200 OK

Console output:

{
    "total_rows":10,
    "offset":0,
    "rows":[
        {
            "id":"d12ee5ea1df6baa2b06451f44a002cef",
            "key":null,
            "value":null
        },
        {
            "id":"d12ee5ea1df6baa2b06451f44a0037b5",
            "key":null,
            "value":null
        },
        {
            "id":"d12ee5ea1df6baa2b06451f44a003b06",
            "key":null,
            "value":null
        },
        …
    ]
}

List

JavaScript example:

$.couch.db("mydb").list("default/all", "all", {
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    },
    reduce: false
});

Resulting HTTP request:

GET http://localhost:5984/mydb/_design/default/_list/all/all?reduce=false 200 OK

The console output will depend on your list’s behavior.

Compact

JavaScript example:

$.couch.db("mydb").compact({
    success: function(data) {
        console.log(data);
    }
});

Resulting HTTP request:

POST http://localhost:5984/mydb/_compact 202 Accepted

Console output:

{
    "ok":true
}

View Cleanup

JavaScript example:

$.couch.db("mydb").viewCleanup({
    success: function(data) {
        console.log(data);
    }
});

Resulting HTTP request:

POST http://localhost:5984/mydb/_view_cleanup 202 Accepted

Console output:

{
    "ok":true
}

Compact View

JavaScript example:

$.couch.db("mydb").compactView("default", {
    success: function(data) {
        console.log(data);
    }
});

Resulting HTTP request:

POST http://localhost:5984/mydb/_compact/default 202 Accepted

Console output:

{
    "ok":true
}

Changes

JavaScript example:

$.couch.db("mydb").changes().onChange(function(data) {
    console.log(data);
});

Resulting HTTP requests:

GET http://localhost:5984/mydb/ 200 OK

GET http://localhost:5984/mydb/_changes?heartbeat=10000&feed=longpoll&since=34 200 OK

This will keep a connection open until changes are detected, and then open up another connection to listen for subsequent changes starting from the next sequence.

Console output when a new document is created:

{
    "results":[
        {
            "seq":35,
            "id":"d12ee5ea1df6baa2b06451f44a01b7b5",
            "changes":[
                {
                    "rev":"1-967a00dff5e02add41819138abb3284d"
                }
            ]
        }
    ],
    "last_seq":35
}

This is very powerful feature. It allows you to listen for any changes to documents in the database and immediately respond to those changes.

Copy Document

JavaScript example:

$.couch.db("mydb").copyDoc("d12ee5ea1df6baa2b06451f44a01b7b5", {
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
}, {
    beforeSend: function(xhr) {
        xhr.setRequestHeader("Destination", "aNewDocId");
    }
});

Resulting HTTP request:

COPY http://localhost:5984/mydb/d12ee5ea1df6baa2b06451f44a01b7b5 201 Created

Console output:

{
    "id":"aNewDocId",
    "rev":"1-967a00dff5e02add41819138abb3284d"
}

Drop Database

JavaScript example:

$.couch.db("mydb").drop({
    success: function(data) {
        console.log(data);
    },
    error: function(status) {
        console.log(status);
    }
});

Resulting HTTP request:

DELETE http://localhost:5984/mydb/ 200 OK

Console output:

{
    "ok":true
}

I’ll be giving a presentation on CouchApps at OSCON if you want to learn more about building CouchApps. This presentation will be a part of the JavaScript and HTML5 track. You can save 20% on registration with the code OS11RAD. I’ll also be presenting a tutorial on Learning CouchDB at OSCON Data.

You can also check out my books Writing and Querying MapReduce Views in CouchDB and Scaling CouchDB if you’re interested in learning more about CouchDB in general.

Update (7/15/2011): Max Ogden has pointed me to Dale Harvey‘s documentation generator for jquery.couch.js and a copy of the generated jQuery CouchDB documentation. Max and Dale are also working on a more flexible jquery.couch2.js.

O’Reilly Radar on CouchDB and HTML5

Bradley Holt — Thu, 30 Jun 2011 15:59:10 +0000

I was recently interviewed by Audrey Watters of O’Reilly Radar on what CouchDB can do for HTML5, web apps and mobile. We discussed CouchDB, CouchApps, JavaScript, HTML5, web applications, mobile application development (Android/iOS), Web Storage, IndexedDB, replication, and “ground computing”. Read the full interview for the details of what we talked about.

I’ll be giving a presentation on CouchApps at OSCON if you want to learn more about CouchApps, JavaScript, and HTML5. This presentation will be a part of the JavaScript and HTML5 track. You can save 20% on registration with the code OS11RAD. I’ll also be presenting a tutorial on Learning CouchDB at OSCON Data.

You can also check out my books Writing and Querying MapReduce Views in CouchDB and Scaling CouchDB if you’re interested in learning more about CouchDB in general.

HTML 5, HTTP Methods & REST

Bradley Holt — Thu, 09 Jul 2009 23:07:00 +0000

Lots of very exciting things are happening right now for us web standards aficionados. The big news is the buzz around HTML 5 and its growing support in modern web browsers (modern meaning not Internet Explorer). The current state of web standards makes it difficult, but certainly not impossible, to use the web as a true application platform. HTML 5 promises to change this (maybe not fully until 2022 — but we’re patient). Many articles have been written about HTML 5 but there’s one tiny, but very important, feature I’d like to focus on here: support for the HTTP PUT and DELETE methods in forms. First, a little bit about REST…

I’ve talked about REST here before but REST is useful for more than just building web services. REST is an abbreviation for representational state transfer and is an architectural style for building software. The web itself is built using REST so it is a proven and scalable architecture. Unfortunately many web developers ignore REST to their detriment. Conforming to REST principles can help with search engine optimization (SEO) as well as make your web applications more usable (through predictability of actions) and scalable (the web itself has scaled to massive proportions).

Using a RESTful approach, every URL is a representation of a resource (a noun). These resources can then be retrieved and manipulated (have their state changed) using a standard set of verbs. These verbs are actually HTTP methods. There are a whole bunch of verbs/HTTP methods but only worry about four of them (at least for now): GET, POST, PUT, and DELETE. Here is an example of how some nouns and verbs can be used to together, borrowing from the Atom Publishing Protocol (APP):

HTTP method	URI	result
GET	/people	GETs a collection of people
POST	/people	POSTs a new person to the collection (using data in the POST request)
GET	/people/bradley-holt	GETs bradley-holt
PUT	/people/bradley-holt	PUTs an updated version of bradley-holt (using data in the PUT request)
DELETE	/people/bradley-holt	DELETEs bradley-holt

The problem was that up until now there was no way to specify a form method other than GET or POST. This meant that everything had to be tunneled through POST (or had to be done using JavaScript) which, while not technically incorrect, was incovenient and did not allow web developers to fully express the intent of user actions. HTML 5 specifies that forms can now have the methods of PUT and DELETE as well. This simple addition is one small way in which HTML 5 will allow the web to become more of a fully-feature application platform.

For you Zend Framework developers: I just learned today that Zend Framework 1.9 will include a new REST router which will help web developers adhere to RESTful principles. Please use it and also use the new PUT and DELETE methods in HTML 5 forms as browser support catches on.

Bradley Holt » HTML5

Top Five Posts of 2011

5. CouchDB and Domain-Driven Design

4. Addressing the NoSQL Criticism

3. Testing PHP 5.4

2. Exploring RabbitMQ and PHP

1. CouchDB jQuery Plugin Reference

CouchApps at CouchConf NYC

CouchApps at jQuery Conference Boston 2011

Speaking at CouchConf NYC

CouchApps at OSCON 2011

CouchDB jQuery Plugin Reference

Setup

Server API

Server Information

All DBs

User Signup

Login

Session

Logout

Active Tasks

Server Configuration

User DB

New UUID

Replicate

Database API

Create Database

Database Info

Save New Document

Open Document

Save Updated Document

Remove Document

Bulk Save

Bulk Remove

All Documents

All Design Documents

All Apps

Query

View

List

Compact

View Cleanup

Compact View

Changes

Copy Document

Drop Database

O’Reilly Radar on CouchDB and HTML5

HTML 5, HTTP Methods & REST