[Couchdb Wiki] Update of "Document_Update_Handlers" by ChristianCarter

[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 ChristianCarter.
The comment on this change is: adding a lot more info based on my documentation at http://couchapp.org/page/update-functions.
http://wiki.apache.org/couchdb/Document_Update_Handlers?action=diff&rev1=14&rev2=15

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

  <<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.
+ 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.  This also allows for the CouchDB server to provide a GET-modify-POST cycle that does not depend on client-side JS to create or edit documents.
  
- 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.
+ The update handler can be passed a document id (via the URI( to show that it will be editing that document, and the server will provide the function with the most recent version of that document.  Anything else passed to the handler happens through the POST/PUT body or the query string, and must be handled in the handler.
  
  == 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.
@@ -69, +69 @@

  }}}
  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 or new) document, which is committed to the database. If the first element is null no document will be committed to the database. The second element is the response that will be sent back to the caller.
+ The handler function takes the most recent version of the document from the database and the http request environment as parameters. It returns a two-element array: the first element is the (updated or new) document, which is committed to the database. If the first element is null no document will be committed to the database. If you are updating an existing, it should already have an `_id` set, and if you are creating a new document, make sure to set its `_id` to something, either generated based on the input or the `req.uuid` provided. The second element is the response that will be sent back to the caller.
+ 
+ == Request ==
+ 
+ The request parameter will look something like this for a update function designed to create a new document:
+ 
+ {{{#!highlight javacript
+     {"info": 
+     	{
+     		"db_name":"loot",
+     		/* and many more */
+     		"committed_update_seq":27
+     	},
+     	"id":null,
+     	"uuid":"7f8a0e3833bcc7161cfab80275221dc1",
+     	"method":"POST",
+     	"path":["loot","_design","haul","_update","new"],
+     	"query":{},
+     	"headers":{"Accept":"application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5" /* and many more */},
+     	"body":"name=Jeff",
+     	"peer":"127.0.0.1",
+     	"form":{"name":"Jeff"},
+     	"cookie":{},
+     	"userCtx":{"db":"loot","name":null,"roles":[]}
+     }
+ }}}
+ 
+ Since no ID was passed, the request doesn't have an ID.  However, the CouchDB server helpfully throws in a UUID so you can create a new document with a unique ID and be sure it won't conflict with any document in the database already.
+ 
+ The server also parses the POST body into a Javascript object called `form` and does the same with the query string, in `query`.
+ 
+ == Response ==
+ The second member of the return array is the HTTP response. This can be a javascript object with headers and a body:
+ 
+ {{{#!highlight javascript
+     var resp =  {
+       "headers" : {
+         "Content-Type" : "application/xml"
+       },
+       "body" : doc.xml
+     };
+ }}}
+ 
+ or just a plain string:
+ {{{
+     <p>Update function complete!</p>
+ }}}
+ Though you can set the headers, right now the status code for an update function response is hardcoded to be 200/201 unless an error occurs.  This is a bug.
+ 
  
  == Usage ==
  To invoke a handler, use one of:
@@ -90, +138 @@

  
  == TBD ==
   * Maybe we should support PATCH?
-  * Must fields be sent as URL query parameters, or can they be sent in the request representation?