Zafu: CouchDB and KendoUI (part 2)


In my previous post I explained how to deploy KendoUI inside CouchDB using CouchApp.

This was a pretty easy thing and (of course) very little benefit since we were not actually saving / retrieving data from the database.

Step1: Using jQuery CouchDB library

jquery.couch.js is the standard API shipped with CouchDB. This is what I’m going to use for Creating, Reading, Updating and Deleting data from CouchDB.

Finding jquery.couch.js

The easiest way for finding jquery.couch.js is getting the one that is shipped inside CouchDB:

  1. Open http://127.0.0.1:5984/_utils/script/jquery.couch.js in your browser and save the file.
  2. Use curl from the command line.
curl http://127.0.0.1:5984/_utils/script/jquery.couch.js > jquery.couch.js

The very initial idea would be linking your HTML with this version (by using relative paths to it) BUT according to some forums (see this) it does not work in mobile environments. Since it is not large, I do also recommend copying it to your _attachments/js folder.

Very quick tutorial about jQuery CouchDB library

NOTE: This is not really a tutorial but some basic notions.
First of all you start thinking in terms of parallelization: I mean, you should not think about methods that you invoke and execution continues when method finishes. Most (all?) methods within CouchDB JavaScript API should be considered as something that you ask for and it will (eventually) finish and you get notified about it (upon successful -or not- completion of it).
Many of jquery.couch.js methods you provide one JSON object with two fields that are callback functions:

var callbacks = {
    success: function () { alert ("Yeah!"); },
    error: function () { alert ("Oops!"); }
}

1. Including the API

After including jQuery library include jquery.couch.js:

<!-- jQuery CouchDB scripts -->
<script src="js/jquery.min.js" type="text/javascript"></script>
<script src="js/jquery.couch.js" type="text/javascript"></script>

2. Accessing the database

Define a variable that we will use throughout the code:

// Reference to the database
var db = $.couch.db("app1");

NOTE: Remember that you might need to login before start using the database.

3. Create document

Invoke saveDoc method from db with two arguments: JSON document being saved and callbacks for success or error.

var db = $.couch.db("app1");
var data = { type:'tick', tick: 'AAPL', name: 'Apple' };
db.saveDoc (data, {
    success: function (d) { alert ("Yeah!: " + d._id); },
    error: function () { alert ("Oops!"); }
});

IMPORTANT:It is very important to note that data should either not include _id field or define it with a value that does not exist. A value that already exists represents a collision and hence an error. An empty string is not valid either.
success receives as argument an object with the identifier (id) and revision (rev) of the created document.

4. Reading a document

Invoke openDoc with document identifier as first argument and callback functions as second.

db.openDoc("63806bde88c403b5c5aadceba60260e9", {
    success: function (d) { alert ("Yeah!" + d.tick + "->" + d.name); },
    error: function () { alert ("Oops!"); }
});

On success you get the document.

5. Updating a document

Invoke saveDoc with the document update (it must include the identifier _id and revision _rev) and callback functions.

var data = { _id:'63806bde88c403b5c5aadceba60260e9', _rev:'1-f10e140d3debd4cd3c524737c2d0e8a6',
    type:'tick', tick: 'AAPL', name: 'Apple Inc.' };
db.saveDoc(data, {
    success: function (d) { alert ("Yeah!" + d.rev); },
    error: function () { alert ("Oops!"); }
});

6. Delete a document

Invoke removeDoc with one JSON object including the document identifier _id and revision _rev and a second argument for the callbacks.

var data = { _id:'63806bde88c403b5c5aadceba60274ef', _rev:'1-c8af95a9d3c4d9ea3cd720f25415ffe9' };
db.removeDoc(data, {
    success: function (d) { alert ("Yeah! " + d.ok); },
    error: function () { alert ("Oops!"); }
});

7. Views

Invoke view with the name of the view that you want to execute. On return you get a JSON structure with a field rows containing a vector with the information retrieved.

db.view("app1/getTicks", {
    success: function (d) { alert ("Yeah! Retrieved: " + d.ok + " documents"); },
    error: function () { alert ("Oops!"); }
});

And that’s about it. For a more complete description of these interfaces, click here!.
Next post (here) is start using it for populating a Kendo UI grid.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s