Forms
Presenting forms to users and handling the response is a common task in a web application. The Haplo Platform helps speed up development of HTML forms, using a declarative approach to describing a form, and a streamlined API for handling the responses.
The forms system scales from a simple form containing a single text field right up to a complex form with tabular data and client side JavaScript UI. Only the necessary scripting support is sent to the client, so simple forms are as lightweight as they would if they had been generated by any other means. Templates are used to customise the layout of the form, and default templates which cover the majority of the cases are included.
As a bonus, it can also generate a static HTML display of the data in the document from the same form specification, often eliminating the need to write custom templates for displaying data manipulated by this system.
Everything is represented as JavaScript data structures, using only values which can be serialised as JSON. These are referred to as JSON documents, although the the forms system doesn’t do any serialisation or decoding of JSON.
Forms can be automatically translated to the user’s current locale when you include translated strings resources in your plugin.
The forms system uses several components. It’s worth being aware of them, but when you’re using the forms system in a request handler, it all pretty much takes care of itself.
Specification
The specification is a JSON document describing the form.
The form is split into sections, which group fields, and form elements, which describe the fields themselves. Sections can be repeating, which allows the user to enter a table of data, adding rows as required.
Form specifications are conventionally stored as JSON files within your plugin’s file/data directory.
Document
The document is a JSON compatible data structure which holds the data being filled in or edited by the user.
As well as normal JavaScript data structures, a document can be any object which allows setting and getting of the properties defined in the specification.
The forms system takes great care to maintain all the data in the document which isn’t mentioned in the specification. You can store extra data in a document, or define multiple forms for the same document, without fear data will be removed.
Description
The description is a FormDescription object which is generated from a specification.
Descriptions can only be created as the plugin is loading, as a side effect of their creation is to make information available at special URLs. As HTTP is stateless and there can be multiple JavaScript runtimes active at once, all descriptions must be available at all times so this information can be generated on demand.
Form elements
A form is made up of one or more form elements. These largely correspond to HTML elements, such as <input>, although use of the more complex elements may trigger the inclusion of client side JavaScript to implement them.
Each form element is specified in the specification, including where the data comes from in the document and the validation rules.
Instance
Once you’ve got a description, you create an instance to generate the HTML form for a given document and handle the response. This is a FormInstance object created by the description.
Data source
Some of the form elements require that the user picks an item from a list. A data source describes these lists, for example, allowing the user to pick a StoreObject from all objects of a given type.