Differences between revisions 1 and 29 (spanning 28 versions)
Revision 1 as of 2009-08-19 14:19:51
Size: 2646
Editor: 157
Comment:
Revision 29 as of 2018-04-13 05:58:47
Size: 0
Editor: JoanTouzet
Comment: Official docs on this are much better.
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
== Basics ==

CouchDB (0.10 and up) has the ability to allow server-side processing of an incoming document before it's committed. This feature allows a range of use cases such as providing a server-side last modified timestamp, etc.

== Implementation ==

This functionality is implemented via document update handlers defined in a design doc. Specifically, in a design doc one defines an "updates" attribute that contains any number of document update handlers. The follow handlers should be self-explanatory as to what they accomplish.

{{{
    updates: {

      "hello" : function(doc, req) {
        if (!doc) {
          if (req.docId) {
            return [{
              _id : req.docId
            }, "New World"]
          }
          return [null, "Empty World"];
        }
        doc.world = "hello";
        doc.edited_by = req.userCtx;
        return [doc, "hello doc"];
      },

      "in-place" : function(doc, req) {
        var field = req.query.field;
        var value = req.query.value;
        var message = "set "+field+" to "+value;
        doc[field] = value;
        return [doc, message];
      },

      "bump-counter" : function(doc, req) {
        if (!doc.counter) doc.counter = 0;
        doc.counter += 1;
        var message = "<h1>bumped it!</h1>";
        return [doc, message];
      },

      "error" : function(doc, req) {
        superFail.badCrash;
      },

      "xml" : function(doc, req) {
        var xml = new XML('<xml></xml>');
        xml.title = doc.title;
        var posted_xml = new XML(req.body);
        doc.via_xml = posted_xml.foo.toString();
        var resp = {
          "headers" : {
            "Content-Type" : "application/xml"
          },
          "body" : xml
        };
         
         return [doc, resp];
       }
    }
}}}

The handler function takes the document and the http request as parameters. It returns a two-element array: the first element is the (updated) document, which is committed to the database. The second element is the response that will be sent back to the caller.

== Usage ==

To invoke a handler, one must "put" the document against the handler function itself. Using the canonical document URL won't invoke any handlers. For example, to invoke the "in-place" handler defined above, the URL to use is:

{{{
http://127.0.0.1:5984/<my_database>/_design/<my_designdoc>/_update/in-place/<mydocId>?field=title&value=test
}}}

This usage seems to indicate that unlike document validators, the user's intend must be clear by calling an individual handler explicitly.