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.