[Couchdb Wiki] Update of "Document_Update_Handlers" by Matt Freeman

[Apache Wiki <wi...@apache.org>]

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?