Simplest possible form

This page describes the most basic form you can build with Kanso

Note

Kanso requieres at least Couchdb 1.1. If you have older version, you must update it first.

Files it relies on

SimplestPossibleForms/
  |-- lib/
        |-- shows.js
        |-- updates.js
  |-- templates/
        |-- form.html
        |-- base.html

The simplest possible form relies on four files. shows.js,updates.js and base.html can be downloaded using git: https://github.com/Spredzy/SimplestPossibleForm:

$ git clone git://github.com/Spredzy/SimplestPossibleForm.git
$ cd SimplestPossibleForm
$ kanso install
$ kanso createdb simplestpossibleform

kanso.json

{
    "name": "my_form",
    "version": "0.0.1",
    "description": "My new CouchApp",
    "load": "lib/app",
    "modules": "lib",
    "attachments": "static",
    "dust": {
        "templates": "templates"
    },
    "duality": {
        "base_template": "base.html"
    },
    "dependencies": {
        "modules": null,
        "properties": null,
        "attachments": null,
        "settings": null,
        "duality": null,
        "dust": null,
        "duality-dust": null,
        "couchtypes": null
    }
}

templates/form.html

<h1>{form_title}</h1>

<form method="{method}" action="{action}">
  <table>
    {form|s}
  </table>
  <input type="submit" value="{button}" />
</form>

The form.html page aims to handle the form we will be generating.

templates/base.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 
  <head> 
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 
    <title>{title}</title> 
  </head> 
  <body> 
    <div id="content">
      {content|s}
    </div>
    <script src="{baseURL}/static/js/jquery-1.5.2.min.js"></script>
    <script src="{baseURL}/static/js/json2.js"></script>
    <script src="{baseURL}/modules.js"></script>
    <script src="{baseURL}/kanso.js"></script>
  </body>
</html>

lib/shows.js

/**
 * Show functions to be exported from the design doc.
 */

var templates = require('duality/templates'),
    fields = require('couchtypes/fields'),
    Form = require('couchtypes/forms').Form;


exports.welcome = function (doc, req) {
    return {
        title: 'It worked!',
        content: templates.render('welcome.html', req, {})
    };
};

exports.not_found = function (doc, req) {
    return {
        title: '404 - Not Found',
        content: templates.render('404.html', req, {})
    };
};

exports.my_form = function (doc, req) {
    var myForm = new Form ({first_name: fields.string(), last_name: fields.string()});
    return {
      title : 'My First Form',
      content: templates.render('form.html', req, {
            form_title : 'My Form',
            method : 'POST',
            action : '../_update/update_my_form',
            form : myForm.toHTML(req),
            button: 'Validate'})
    }
};

exports.my_form_content = function(doc, req) {
    return {
        title: 'Content of my Form',
        content: templates.render('base.html', req, {content : '<b>First Name</b> : ' +  doc.first_name + '<br/><b>Last Name</b> : ' + doc.last_name}) 
    };
};

We've declared two functions :

  • my_form: my_form function creates the form and renders it. We've instantiated a form with two string elements (first_name and last_name) then rendered it with the attributes we wanted.

  • my_form_content: my_form_content function simply displays the content of a document previously saved via the form.

Notes. couchtypes/fields and couchtypes/forms needs to be required.

lib/updates.js

/**
 * Update functions to be exported from the design doc.
 */


var templates = require('duality/templates'),
    fields = require('couchtypes/fields'),
    Form = require('couchtypes/forms').Form;

exports.update_my_form = function (doc, req) {
    var form = new Form({first_name: fields.string(), last_name: fields.string()});
    form.validate(req);

    /**
     * We do that because we are not using CouchType
     * CouchType takes care of generating a uuid
     */
    form.values._id = req.uuid;

 if (form.isValid()) {
        return [form.values, {content: 'Hello ' + form.values.first_name +', '+ form.values.last_name , title: 'Result'}];
    }
 else {
        var content = templates.render('form.html', req, {
            form_title: 'My Form',
            method: 'POST',
            action: '../_update/update_my_form',
            form: form.toHTML(req),
            input: 'Validate'
        });
        return [null, {content: content, title: 'My First Form'}];
    }
};

The update_my_form function, creates a new instance of Form with the exact same pattern as the one instantiated in the shows.js file, runs it against validation function and if the form is valid the content is added (and the content shown) else the form is rerendered.

For more informations about CouchDb _updates function see CouchDb Wiki.

Extra (optional)

In order for the URL kanso gives you after pushing to match the URL form edit lib/rewrites.js

Change

{from: '/', to: '_show/welcome'},

To

{from: '/', to: '_show/my_form'},

Bottom line

kanso install
kanso push http://127.0.0.1:5984/simplestpossibleform

Admiting that the name of your app defined in kanso.json is simplestpossibleform :

There you go ! You made it through your first form.

Next

Use CouchTypes instead of plain fields : CouchTypes forms