Specification

Specifications are JSON documents which describe a form. To implement a form, FormDescription objects are created from specifications using the form() method on your plugin object.

Form specifications are conventionally stored as JSON files within your plugin’s file/data directory.

See a simple usage example for how specifications are used to handle forms.

Specification root

The root of the specification contains the following properties:

`specificationVersion`	Must be `0`
`formId`	A unique identifier for the form, unique within this plugin only. Formed from `a-z0-9_`
`formTitle`	A human readable name of the form.
`formTitleShort`	A shorter version of the human readable name of the form, defaulting to `formTitle` if not specified.
`elements`	The elements of the top level section.
`inlineGuidanceNoteTemplate`	(optional) The path to the file containing the templates for guidance notes.
(section properties)	Other properties from the Section specification, including template choice.

Form elements

Each form element in the specification is a JSON compatible JavaScript object. The properties define the element. Some properties are dependent on the type, but the majority are common to all elements.

Common properties

`type`	The type of the form element.
`path`	The location of the value within the document as a series of `.` separated property names. See Value path handling for details.
`label`	(optional) The human readable label to display on the form above this element.
`explanation`	(optional) Non-bold text to be displayed between the label and element, will not be displayed in the document.
`name`	(optional) The name of the form element, corresponding to `name` attributes within the HTML. If it isn’t specified, and there is a `label` property, the name of the element is generated from the `label`. Otherwise it is automatically generated, which is not entirely advisable.
`required`	(optional) If `true`, or a conditional statement which evaluates to true, this is a required field.
`deprecated`	(optional) If `true`, this is a deprecated element. If the value exists in the document, it will be displayed and editable, but if not, the element is never rendered.
`defaultValue`	(optional) The default value for this element, in the format expected by the form element.
`id`	(optional) The HTML `id` attribute for the form element. Do not use for form elements within repeating sections.
`class`	(optional) The HTML `class` attribute for the form element.
`placeholder`	(optional) If the form element supports it, the placeholder text to display when the field is empty.
`guidanceNote`	(optional) The text of a note which is displayed when the user focuses on this field.
`inForm`	(optional) If `true`, or a conditional statement which evaluates to true, the element is included in the form. Defaults to `true`. Consider using `include` instead.
`inDocument`	(optional) If `true`, or a conditional statement which evaluates to true, the element is displayed in the document. Defaults to `true`. Consider using `include` instead.
`include`	(optional) A shortcut which sets `inForm` and `inDocument` to the same value. Use to control inclusion of the element in both form and document with a single property.
`inlineGuidanceNote`	(optional) Either a view to be passed to the template specified by `inlineGuidanceNoteTemplate` or a string.
`validationCustom`	(optional) The specification for a validation function to provide custom validation for this element. See Custom validation.

Text

All user visible text in forms, like label, heading, etc, uses NAME() string interpolation to translate names of things where names are marked as NAME(name). Note there are no quotes within the brackets.

For example:

  {
    "type": "paragraph",
    "path": "example",
    "label": "Comments from NAME(Head of Department)"
  }

Autofocus

The client side JavaScript forms support will auto-focus into the first text field. You can skip an element by applying the oforms-no-autofocus class using the class property, or by applying this class to any of its parent elements in the DOM.

Form element types

Boolean
Choice
Date
Display value
Document text
File
File repeating section
Lookup
Measurement
Number
Paragraph
Render template
Repeating section
Section
Static
Text