Dear wiki user, You have subscribed to a wiki page "Couchdb Wiki" for change notification.
The page "Document_Update_Handlers" has been deleted by JoanTouzet: https://wiki.apache.org/couchdb/Document_Update_Handlers?action=diff&rev1=28&rev2=29 Comment: Official docs on this are much better. - <<Include(EditTheWiki)>> - ## page was renamed from Document Update Handlers - ## page was renamed from How_to_intercept_document_updates_and_perform_additional_server-side_processing - = Document Update Handlers = - - See also the [[http://docs.couchdb.org/en/latest/ddocs.html#update-functions|official documentation]] for this topic. - - <<TableOfContents()>> - - == Basics == - Update handlers are functions that clients can request to invoke server-side logic that will create or update a document. 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. - - When the request to an update handler includes a document ID in the URL, the server will provide the function with the most recent version of that document. You can provide any other values needed by the update handler function via the POST/PUT entity body or query string parameters of the request. - - This feature was first implemented in CouchDB version 0.10. - - == Creating an Update Handler == - You can specify any number of update handler functions in a design document, under the "updates" attribute. - - For example: - - {{{#!highlight javascript - { - updates: { - - "hello" : "function(doc, req) { - if (!doc) { - if (req.id) { - return [{ - _id : req.id - }, '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.form.field; - var value = req.form.value; - var message = 'set '+field+' to '+value; - doc[field] = value; - return [doc, message]; - }", - - "in-place-query" : "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 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. - - If you want the client to get the changed document (without an additional request) you can return it as the second element of the return array, but you need to turn it into a string first. - - {{{#!highlight javascript - { - updates: { - "in-place": "function (doc, req) { - doc.field = req.form.field.new_value; - - return [doc, toJSON(doc)]; - }" - } - } - }}} - '''Note''' The document returned in this manner will have the "old" _rev, see the response section for how retrieve the new/current _rev. - - == Request == - The request parameter will look something like this for a update function designed to create a new document: - - {{{#!highlight javascript - { - "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 provides 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 == - If the first member of the return array is a document the HTTP response headers include a "X-Couch-Update-NewRev" with the _rev number from the document after the change/create has been applied. This can be used to keep the client's object in sync with that in the database. - - 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> - }}} - In addition to setting headers, you may set a `code` attribute on the object in order to control the HTTP status. - - == Usage == - 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-query` handler defined above, PUT to: - - {{{ - http://127.0.0.1:5984/<my_database>/_design/<my_designdoc>/_update/in-place-query/<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. -
