Skip to main content

Next generation forms in javascript

Project description

The gocept.jsform distribution

JavaScript library for simple creation of forms in your clients browser. It just needs a JSON datastructure and creates a form with auto saving fields from it.

Uses knockout for data-binding, json-template for templating and jquery for DOM manipulation and ajax calls.


If you have a server using fanstatic to include resources, just do:

from gocept.jsform import jsform

This will require all needed resources like jquery, knockout, json-template, widgets and the code to setup and run gocept.jsform itself.

Without fanstatic, you should include the following resources by hand:

  • ko.mapping.js
  • helpers.js
  • jsform.js

You can find them in the resources directory in this package. Also, there are some widget templates there, named gocept_jsform_templates_*.pt. You’ll have to include those you need as scripts of type text/html with an appropriate id, for example:

<script type="text/html" id="gocept_jsform_templates_form">
  <form method="POST" action="{action}" id="{form_id}">

where the lines between the script tags are the content of the respective template file.


All you need to start creating forms is:

<div id="replace_this_with_my_form"></div>

<script type="text/javascript">
  var my_form = new gocept.jsform.Form('replace_this_with_my_form');

This will inject the form in the container with the id replace_this_with_my_form, load the form data via ajax from the url form_data.json and create input fields according to the content of form_data.json.

form.load() accepts javascript objects as data or a url (like in the example above). It then guesses, which field widget to load by means of the datatype of your field:

    {firstName: '', // will result in a input field with type="text"
     title: [{id: 'mr', value: 'Mister'},
             {id: 'mrs', value: 'Miss', selected: true}], // will result in a select box
     needs_glasses: false}); // will result in a checkbox

gocept.jsform comes with basic templates for these three use cases. Of cource you can provide your own templates for either the form or the fields itself. Please refer to the customization section for further information.


The tests are written in jasmine and run using selenium webdriver.


There are various options which can be passed to customize the HTML output and the behaviour of gocept.jsform.

Providing a save url for the server

The great thing about gocept.jsform is, that it automatically pushes changes in your form fields to the server. For that to work you need to specify a url where gocept.jsform should propagate changes to:

var form = new gocept.jsform.Form('my_form', {save_url: '/save.json'});

On every change, the following information is pushed to that url:

  • id: the name of the field (e.g. firstname)
  • value: the new value for that field (e.g. Bob)

The server should now validate the given data. If saving went fine, it must return {status: 'success'}, if there was a (validation-) error, it must return e.g. {status: 'error', msg: 'Not a valid email address'}. The error will then be displayed next to the widget.

Customizing the form template

The default behaviour is to simply append every new field in the form tag. If you would like to customize the order of your fields or just need another boilerplate for you form, you can use a custom form template with containers for all or just some of the fields:

var template = new jsontemplate.Template(
  ['<form method="POST" action="{action}" id="{form_id}">',
   '<table><tr><td class="firstname"><span id="firstname" /></td>',
   '<td class="lastname"><span id="lastname" /></td></tr></table>',
  {default_formatter: 'html'});

var form = new gocept.jsform.Form('my_form', {form_template: template});
form.load({firstname: 'Max', lastname: 'Mustermann'});

This will replace the span containers with id firstname and lastname with the appropriate input fields.

Customizing field widgets

You can either customize widgets by their type (e.g. all fields rendered for strings) or customize single widgets by their name.

Customization by field type

You can overwrite the default templates by providing your own templates in the options dict passed during form initialization:

var form = new gocept.jsform.Form(
  'my_form', {string_template: my_input_template,
              object_template: my_select_template,
              boolean_template: my_checkbox_template});

For every string data, your input template would be rendered instead of the default input text field. Same for lists and boolean values.

Customization by field name

Imagine you want checkboxes instead of a select field:

var template = new jsontemplate.Template(
  ['<div class="title">Titel:',
   '{.repeated section value}',
   '  <div>',
   '    <input type="radio" name="{name}" value="{id}" class="{id}"',
   '           data-bind="checked: {name}" /> {value}',
   '  </div>',
   '</div>'].join(''), {default_formatter: 'html'});

var form = new gocept.jsform.Form('my_form');
form.load({title: [{id: 'mr', value: 'Mr.'},
                   {id: 'mrs', value: 'Mrs.'}]},
          {title: {template: template}});

You can pass the load method a JS object containing customizations for each field. One of these customization options is template, which results in rendering two checkboxes instead of the default select box in the above example.

You can also specify a label or other options for the fields:

var template = new jsontemplate.Template(
  ['{label}: <input type="text" name="{name}" value="{default}"',
   '                data-bind="value: {name}" {readonly} />'].join(''),
  {default_formatter: 'html', undefined_str: ''});

var form = new gocept.jsform.Form('my_form');
form.load({firstname: 'Sebastian'},
          {firstname: {template: template,
                       label: 'First name',
                       default: 'Max'}});

Change log for gocept.jsform

1.1 (2014-04-07)

  • Propagate save message of server using after-save trigger.
  • Added infrastructure for displaying and clearing status messages, use it for announcing HTTP faults during AJAX calls.
  • Display and clear field-related errors both at the widget and via status messages.
  • When saving data, count anything but a JSON response with a status value of “success” as an error. Give up completely after an incomprehensible response, retry on connection errors either after the next successful server access for any other field, or when requested by a call to retry().
  • Added an API method save_remaining() that causes any fields to be saved that have not been modified so far. While this should only save the initial values loaded from the server, it is useful to apply the same validation and error handling to all fields.
  • Added an API method when_saved(retry) that returns a promise that aggregates any pending and completed save calls, either propagating the retry behaviour of single fields (the default) or failing on server errors.
  • Provide a visual clue and status message while saving a field.
  • Some refactoring to improve code readability.
  • Made code pass jshint check.
  • Made default and currently not overrideable status message behaviour compatible to bootstrap 3
  • Properly unsubscribe change handlers when updating fields.
  • Added simple localization.

1.0 (2013-12-13)

  • Remove console calls as they are not understood by all browsers.

0.8 (2013-12-10)

  • Fixed: jsform did not render in IE8 if form template started with line break.

0.7 (2013-12-03)

  • Add ability to send a CSRF token with every request. This token must be available via the id csrf_token (can be customized) in the DOM.
  • Added minified versions of javascript resources.

0.6 (2013-09-06)

  • Bugfix: Use indexOf instead of startsWith, which is not available on all browsers.

0.5 (2013-09-06)

  • Declare for attribute on form labels.
  • Store “save on change” subscriptions so they can be cancelled.
  • Ignore null values for data fields. (#1)

0.4 (2013-08-27)

  • Made it possible to define templates as template files on file system.

0.3 (2013-08-27)

  • Add events after-load and after-save.
  • Fix JSON serialization to be able to handle Knockout observables.
  • Added reload functionality to the form class.

0.2 (2013-08-26)

  • Made it possible to preselect values in arrays when the form is rendered.
  • Changed form submit behaviour:
    • Default submit type is not POST instead of GET. (Change it with the save_type option)
    • Data is now submitted as JSON type.

0.1 (2013-08-17)

initial release

Project details

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date (56.3 kB) Copy SHA256 hash SHA256 Source None Apr 7, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page