couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Couchdb Wiki] Update of "Document_Update_Handlers" by Matt Freeman
Date Mon, 06 Dec 2010 03:08:49 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The "Document_Update_Handlers" page has been changed by Matt Freeman.
http://wiki.apache.org/couchdb/Document_Update_Handlers?action=diff&rev1=12&rev2=13

--------------------------------------------------

  <<TableOfContents()>>
  
  == Basics ==
- 
  CouchDB (0.10 and up) has the ability to allow server-side updating of a document without
the usual GET-modify-POST cycle, or server-side creation of a new document based on parameters
sent by the user. This feature allows a range of use cases such as providing a server-side
last modified timestamp, updating individual fields in a document without first getting the
latest revision, etc.
  
  It's important to note that and update handler doesn't need to have an entire document sent
to it, as it will be passed the server's current version of the requested document. In fact,
any parameters passed to an update function, other than the document ID, have to be handled
manually by the update function itself.
  
  == 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. 
+ 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.
  
  {{{#!highlight javascript
  {
@@ -21, +19 @@

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

          },
          "body" : xml
        };
-      
+ 
         return [doc, resp];
       }
    }
  }
  }}}
- 
  NOTE: '''The functions should be quoted'''.
  
  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, use one of:
  
- To invoke a handler, use one of:
   * a PUT request against the handler function with a document id: `/<database>/_design/<design>/_update/<function>/<docid>`
   * a POST request agasint the handler function without a document id: `/<database>/_design/<design>/_update/<function>`
+ 
+ The document id specified in a PUT request URI is available in the update handler as id
property on the request object (req.id).
  
  For example, to invoke the `in-place` handler defined above, PUT to:
  
  {{{
  http://127.0.0.1:5984/<my_database>/_design/<my_designdoc>/_update/in-place/<mydocId>?field=title&value=test
  }}}
- 
  This means that unlike document validators, the user's intent must be clear by calling this
individual handler explicitly. In this sense, you should think about an ''_update'' handler
as complementary to ''_show'' functions, not to ''validate_doc_update'' functions.
  
  For more information, look at ''update_documents.js'' in the test suite.
  
  == TBD ==
- 
   * Maybe we should support PATCH?
   * Must fields be sent as URL query parameters, or can they be sent in the request representation?
  

Mime
View raw message