oForms: Scalable JSON forms

A scalable JSON forms system, written in JavaScript, for the Haplo Platform but designed to be integrated into any other JavaScript application.

Taking a form specification as a JSON-compatible JavaScript data structure, and a JSON document, it outputs an HTML form, updates the document when values are submitted, and can output a default rendering of the data based on the specification.

The focus on JSON means it’s easy to work with, both for handling the data and programmatically manipulating form definitions.

It’s “scalable” because it’ll do a simple text field without any overhead, but will scale up to big complex forms with client side JavaScript when needed.

It’s designed to be easy to plug into any web app framework, both client and server side. While it’s intended to be “wrapped” by a small framework specific layer, it can be used without.

The default templates work with Twitter Bootstrap. If you don’t use Bootstrap in your project, the minimal oforms.css file will add the few styles needed and inherit the look of your stylesheets. There’s also “bootstrapish” stylesheet supplied which looks roughly like Bootstrap, but is much smaller.

The templating system uses either Mustache or Handlebars.

Why yet another HTML forms system?

Designed to be really easy to use.
Designed to seamlessly integrate into anything, rather than being tied to a particular framework.
Work with complex JSON documents, or the properties on any JavaScript object.
Run anywhere there’s a JavaScript interpreter, server or client side.
Make the hard things easy, like repeating rows for entering tabular data, without being heavyweight if you don’t use them.
Supports user supplied templates for rendering the forms, with sensible defaults built in.

Project status

oForms is written to provide forms support for the Haplo Platform, and is used in production applications. The feature set is focused on meeting the requirements of the Platform, but it’s developed as a standalone project intended for use elsewhere.

It should implement everything needed for most forms, and is under active development to add the missing features and extend its capabilities.

The build system generates single JavaScript files for all the various variants (server or client side, choice of templating system) and the client side support.

Documentation

Currently only the user-facing side of an integrated version of oForms is documented:

An example of platform integration can be found here.

Also see the test/server_root/test/test.js file for a very simple example of how to use the basic API.

Dependencies

Either Mustache or Handlebars
underscore.js
jQuery (For implementing the advanced client-side features only. It’s written to be as small as possible and make it easy to rewrite for a different client-side library.)

For development, JRuby is required for the build system and test server. Rhino is used to run an embedded JSHint to automatically check all the JavaScript.

Development notes for a UNIX like OS

Setup

Make sure Java is installed.

Download the current release of JRuby. Choose the “binary tar.gz” version.

Decompress the downloaded file, then rename the extracted folder to jruby (without the version number).

Install the required gems with

    export PATH=$PATH:/path/to/jruby/bin
    jgem install jruby-openssl
    jgem install json
    jgem install mongrel

changing /path/to/jruby/bin to the actual location of the jruby/bin directory.

Add a copy of the Rhino interpreter:

Download the 1.7R3 release from http://www.mozilla.org/rhino/ .

Extract the zip file. Copy the js.jar file as build/thirdparty/js-1.7R3.jar .

Developing

Running the test server:

    jruby test_server.rb

Then open http://127.0.0.1:5656/ in your browser.

The JavaScript files sent to the browser are assembled from fragments in the src/*/ directories. The *.rb file in that directory specifies the files which are assembled.

After serving a file, the test server runs it through JSHint. If there are any errors, it’ll print them out, mapping line numbers to the correct fragments.

The templates for the form layouts are in src/oforms/std_templates. The build system includes them in the JavaScript file, and removes the newlines and whitespace at the beginning and end of lines.

The templates are a modified version of Mustache which can be easily converted into both Mustache and Handlebars templates with regular expressions. Templates provided by the user are in the normal format for your chosen templating system.

Test form

test/ contains a test form and some scripting to help see what’s going with the underlying JSON document, and re-render the form or output the document. The test form should output all possible HTML, although it may not cover all possible options for the Elements themselves.

oforms_jquery

This is only required if a form has elements which require client side support, such as repeating sections or look up fields. If a form is simple, it shouldn’t require this client side support, and every effort should be made to avoid requiring it for all forms.

Twitter Bootstrap

oForms outputs Twitter Bootstrap compatible HTML, but offers a minimal stylesheet which works in just about any sensible HTML page layout.

The test page includes links to choose which stylesheet and templating system to use. This just selectively includes parts of the HTML file marked with comments.

Copyright and license

Mozilla Public License Version 2.0, see LICENSE.txt

Contributors

Ben Summers, Haplo (design and implementation)

Matt Tarbit, Isotoma (visual appearance)

kaelifa / oforms