FormInstance interface
A JavaScript object implementing the FormInstance interface describes an instance of a form, and is used to display the form, validate the fields, and update a document data structure with the submitted data.
Construction
Use the instance(document) method on a FormDescription object.
Usage
FormInstance objects are created and used for handling a form using data from, and updating data in, the document passed when constructing the object.
These objects are lightweight, and should not be persisted across requests.
Interface
property complete
true if the form was submitted and all the data is valid, false otherwise.
property document
The document used to create this instance.
function update(request)
If the request represents a POST form submission, update the document with the submitted data.
Within a request handler, use E.request as the request argument.
Returns true if the form was submitted and all the data is valid, false otherwise, and updates the complete property.
Unless this function returns true, the document may contain invalid data.
function renderForm()
Renders the current state of the form as HTML, for inclusion in a template. This includes data from the current state of the document and error messages.
Behind the scenes, the necessary JavaScript is set to be included in the response.
function deferredRenderForm()
Deferred render of the current state of the form, returning a object which can be used with the render() template function.
function renderDocument()
Renders the document as HTML, using the form description to lay out the fields.
function deferredRenderDocument()
Deferred render of the document, returning a object which can be used with the render() template function.
function choices(name, choices)
Sets instance choices for use by choice elements. This must be called before update() or renderForm().
Use one of the Array formats described in Specifying the choice list.
function externalData(source)
Shallow copies all properties (arbitrary key/value pairs) in the source object to the externalData object that is used by Conditional statements, Custom validation and Render template. This must be called before update() or renderForm().
Use this instead of modifying the document just to have something available to the form in order to include form elements etc.
function customValidation(name, fn)
Register a custom validation function. See Custom validation for details.
It may be more convenient to register it globally with globalFormsCustomValidationFunction().
function documentWouldValidate()
Returns true if the document would pass validation if rendered as a form and submitted by the user.
You probably won’t need to use this function, as you will generally check the complete property after a form has been submitted.
function makeView()
Returns a copy of the document, with values replaced by display names where appropriate.
If renderDocument() is not suitable for rendering the document, this function can be useful for generating a view for a template, avoiding lots of fiddly code to look up IDs and choices.