couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From woh...@apache.org
Subject [couchdb-documentation] 01/02: Add best practices sec, migrate "Working_with_Forms"
Date Thu, 05 Apr 2018 20:50:50 GMT
This is an automated email from the ASF dual-hosted git repository.

wohali pushed a commit to branch migrate-working-with-forms
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit 4d85f4da41c0f218102229fef1e6ce95a7f9863d
Author: Joan Touzet <joant@atypical.net>
AuthorDate: Thu Apr 5 16:34:13 2018 -0400

    Add best practices sec, migrate "Working_with_Forms"
    
    This is the start of The Great Wiki Migration. We need a "best
    practices" section for a bunch of these things to land.
    
    To ensure no copyright concerns, the text and example have been
    rewritten from scratch.
---
 src/best-practices/forms.rst | 143 +++++++++++++++++++++++++++++++++++++++++++
 src/best-practices/index.rst |  27 ++++++++
 src/index.rst                |   1 +
 3 files changed, 171 insertions(+)

diff --git a/src/best-practices/forms.rst b/src/best-practices/forms.rst
new file mode 100644
index 0000000..e0e6d0c
--- /dev/null
+++ b/src/best-practices/forms.rst
@@ -0,0 +1,143 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _best-practices/forms:
+
+====================================
+Document submission using HTML Forms
+====================================
+
+It is possible to write to a CouchDB document directly from an HTML form by
+using a document :ref:`update function <updatefun>`. Here's how:
+
+The HTML form
+=============
+
+First, write an HTML form. Here's a simple "Contact Us" form excerpt:
+
+.. code-block:: html
+
+    <form action="/dbname/_design/ddocname/_update/contactform" method="post">
+        <div>
+            <label for="name">Name:</label>
+            <input type="text" id="name" name="name" />
+        </div>
+        <div>
+            <label for="mail">Email:</label>
+            <input type="text" id="mail" name="email" />
+        </div>
+        <div>
+            <label for="msg">Message:</label>
+            <textarea id="msg" name="message"></textarea>
+        </div>
+    </form>
+
+Customize the ``/dbname/_design/ddocname/_update/contactform`` portion of the
+form action URL to reflect the exact path to your database, design document
+and update function (see below).
+
+As CouchDB
+:ref:`no longer recommends the use of CouchDB-hosted web applications <indexes>`
+, you may want to use a reverse proxy to expose CouchDB as a subdirectory of
+your web application.  If so, add that prefix to the ``action`` destination in
+the form.
+
+Another option is to alter CouchDB's :ref:`CORS <cors>` settings and use a
+cross-domain POST. *Be sure you understand all security implications before
+doing this!*
+
+The update function
+===================
+
+Then, write an update function. This is the server-side JavaScript function
+that will receive the ``POST``-ed data.
+
+The first argument to the function will be the document that is being processed
+(if it exists). Because we are using ``POST`` and not ``PUT``, this should be
+empty in our scenario - but we should check to be sure. The ``POST``-ed data
+will be passed as the second parameter to the function, along with any query
+parameters and the full request headers.
+
+Here's a sample handler that extracts the form data, generates a document _id
+based on the email address and timestamp, and saves the document. It then
+returns a JSON success response back to the browser.
+
+.. code-block:: javascript
+
+    function(doc, req) {
+
+        if (doc) {
+            return [doc, toJSON({"error": "request already filed"})]
+        }
+
+        if !(request.form && request.form.email) {
+            return [null, toJSON({"error": "incomplete form"})]
+        }
+
+        var date = new Date()
+        var newdoc = req.form
+        newdoc._id = req.form.email + "_" + date.toISOString()
+
+        return [newdoc, toJSON({"success":"ok"})]
+    }
+
+Place the above function in your design document under the ``updates`` key.
+
+Note that this function does not attempt any sort of input validation or
+sanitization. That is best handled by a
+:ref:`validate document update function <vdufun>` instead.  (A "VDU" will
+validate any document written to the database, not just those that use your
+update function.)
+
+If the first element passed to ``return`` is a document, the HTTP response
+headers will include ``X-Couch-Id``, the ``_id`` value for the newly created
+document, and ``X-Couch-Update-NewRev``, the ``_rev`` value for the newly
+created document. This is handy if your client-side code wants to access or
+update the document in a future call.
+
+Example output
+==============
+
+Here's the worked sample above, using ``curl`` to simulate the form POST.
+
+.. code-block:: bash
+
+    $ curl -X PUT localhost:5984/testdb/_design/myddoc -d '{ "updates": { "contactform":
"function(doc, req) { ... }" } }'
+    {"ok":true,"id":"_design/myddoc","rev":"1-2a2b0951fcaf7287817573b03bba02ed"}
+
+    $ curl --data "name=Lin&email=lin@example.com&message=I Love CouchDB" http://localhost:5984/testdb/_design/myddoc/_update/contactform
+    *   Trying 127.0.0.1...
+    * TCP_NODELAY set
+    * Connected to localhost (127.0.0.1) port 5984 (#1)
+    > POST /testdb/_design/myddoc/_update/contactform HTTP/1.1
+    > Host: localhost:5984
+    > User-Agent: curl/7.59.0
+    > Accept: */*
+    > Content-Length: 53
+    > Content-Type: application/x-www-form-urlencoded
+    >
+    * upload completely sent off: 53 out of 53 bytes
+    < HTTP/1.1 201 Created
+    < Content-Length: 16
+    < Content-Type: text/html; charset=utf-8
+    < Date: Thu, 05 Apr 2018 19:56:42 GMT
+    < Server: CouchDB/2.2.0-948a1311c (Erlang OTP/19)
+    < X-Couch-Id: lin%40example.com_2018-04-05T19:51:22.278Z
+    < X-Couch-Request-ID: 03a5f4fbe0
+    < X-Couch-Update-NewRev: 1-34483732407fcc6cfc5b60ace48b9da9
+    < X-CouchDB-Body-Time: 0
+    <
+    * Connection #1 to host localhost left intact
+    {"success":"ok"}
+
+    $ curl http://localhost:5984/testdb/lin\@example.com_2018-04-05T19:51:22.278Z
+    {"_id":"lin@example.com_2018-04-05T19:51:22.278Z","_rev":"1-34483732407fcc6cfc5b60ace48b9da9","name":"Lin","email":"lin@example.com","message":"I
Love CouchDB"}
diff --git a/src/best-practices/index.rst b/src/best-practices/index.rst
new file mode 100644
index 0000000..40d1e4d
--- /dev/null
+++ b/src/best-practices/index.rst
@@ -0,0 +1,27 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _best-practices:
+
+==============
+Best Practices
+==============
+
+In this chapter, we present some of the best ways to use Apache CouchDB. These
+usage patterns reflect many years of real-world use. We hope that these will
+jump-start your next project, or improve the performance of your current
+system.
+
+.. toctree::
+    :maxdepth: 2
+
+    forms
diff --git a/src/index.rst b/src/index.rst
index 74c92f6..09b8f3d 100644
--- a/src/index.rst
+++ b/src/index.rst
@@ -33,6 +33,7 @@ Table of Contents
     externals
     query-server/index
     fauxton/index
+    best-practices/index
     api/index
     cluster/index
     json-structure

-- 
To stop receiving notification emails like this one, please contact
wohali@apache.org.

Mime
View raw message