Anatomy of a Preside form definition file

Form element

All forms must have a root form element that contains one or more tab elements.

<?xml version="1.0" encoding="UTF-8"?>
<form i18nBaseUri="system-config.sentry:" tabsPlacement="left" extends="my.other.form">
    <tab>
        <!-- ... -->
    </tab>
</form>

Attributes

i18nBaseUri (optional)	Base i18n resource URI to be used when calculating field labels, tab titles, etc. using convention. For example, "my.form:" would lead to URIs such as "my.form:tab.basic.title", etc.
tabsPlacement (optional)	Placement of the tabs UI in the admin. Valid values are: left, right, below and top (default)
extends (optional)	ID of another form whose definition this form should inherit and extend. See Merging Preside form definitions for more details.

Tab element

The tab element defines a tab pane. In the admin interface, tabs will appear using a twitter bootstrap tabs UI; how tabs appear in your application's front end is up to you. All forms must have at least one tab element; a form with only a single tab will be displayed without any tabs UI.

A tab element must contain one or more fieldset elements.

<?xml version="1.0" encoding="UTF-8"?>
<form i18nBaseUri="system-config.sentry:" tabsPlacement="left">
    <tab id="auth" sortorder="10">
        ...
    </tab>
    <tab id="advanced" sortorder="20">
        ...
    </tab>
</form>

Attributes

All attributes below are optional, although id is strongly advised. title and description attributes can be left out and defined using convention in i18n .properties file (see the i18nBaseUri form attribute above).

id	A unique identifier value for the tab, e.g. "standard"
sortorder	A value to determine the order in which the tab will be displayed. The lower the number, the earlier the tab will be displayed.
title	A value that will be used for the tab title text. If not supplied, this will default to {i18nBaseUrl}tab.{tabID}.title (see Preside form definitions and i18n for more details).
iconClass	Class to use to render an icon for the tab, e.g. "fa-calendar" (we use Font Awesome for icons). If not supplied, this will default to {i18nBaseUrl}tab.{tabID}.iconClass (see Preside form definitions and i18n for more details).
decription	A value that will be used for the tab and generally output within the tab content section. If not supplied, this will default to {i18nBaseUrl}tab.{tabID}.description (see Preside form definitions and i18n for more details).

Fieldset elements

A fieldset element can be used to group associated form elements together and for providing some visual indication of that grouping.

A fieldset must contain one or more field elements.

<?xml version="1.0" encoding="UTF-8"?>
<form i18nBaseUri="system-config.sentry:" tabsPlacement="left">
    <tab id="auth" sortorder="10">
        <fieldset id="authbasic" sortorder="10">
            ...
        </fieldset>
        <fieldset id="authadvanced" sortorder="10">
            ...
        </fieldset>
    </tab>
    ...
</form>

Attributes

id	A unique identifier value for the fieldset, e.g. "main"
title	A value or i18n resource URI that will be used for the fieldset title text. If not supplied, this will default to {i18nBaseUrl}fieldset.{fieldsetID}.title (see Preside form definitions and i18n for more details).
decription	A value or i18n resource URI that will be used for the fieldsets description that will be displayed before any form fields in the fieldset. If not supplied, this will default to {i18nBaseUrl}fieldset.{fieldsetID}.description (see Preside form definitions and i18n for more details).
sortorder	A value to determine the order in which the fieldset will be displayed within the parent tab. The lower the number, the earlier the fieldset will be displayed.

Field elements

Field elements define an input field for your form. The attributes required for the field will vary depending on the form control defined (see Preside form controls).

A field element can have zero or more rule child elements for defining customized validation rules.

<?xml version="1.0" encoding="UTF-8"?>
<form i18nBaseUri="system-config.sentry:" tabsPlacement="left">
    <tab id="auth" sortorder="10">
        <fieldset id="authbasic" sortorder="10">
            <field name="api_token" control="password" maxLength="50" />
            <field binding="sentry.configuration_option" />
        </fieldset>
        ...
    </tab>
    ...
</form>

Attributes

name	Unique name of the form field. Required if binding is not used.
binding	Defines a preside object property from which to derive the field definition. Required if name is not used. See Using Preside data objects with form definitions for further details.
control	Form control to use for the field (see Preside form controls). If not supplied and a preside object property binding is defined, then the system will automatically select the appropriate control for the field. If not supplied and no binding is defined, then a default of "textinput" will be used.
label	A label for the field. If not supplied, this will default to {i18nBaseUrl}field.{fieldName}.title (see Preside form definitions and i18n for more details).
placeholder	Placeholder text for the field. Relevant for form controls that use a placeholder (text inputs and textareas). If not supplied, this will default to {i18nBaseUrl}field.{fieldName}.placeholder (see Preside form definitions and i18n for more details).
help	Help text to be displayed in help tooltip for the field. If not supplied, this will default to {i18nBaseUrl}field.{fieldName}.help (see Preside form definitions and i18n for more details).
sortorder	A value to determine the order in which the field will be displayed within the parent fieldset. The lower the number, the earlier the field will be displayed.

Rule elements

A rule element must live beneath a field element and can contain zero or more param attributes. A rule represents a validation rule and deeply integrates with the Validation framework. See Preside form validation for full details of validation with preside forms.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<form i18nBaseUri="system-config.sentry:" tabsPlacement="left">
    <tab id="auth" sortorder="10">
        <fieldset id="authbasic" sortorder="10">
            <field name="api_token" control="password" maxLength="50" />
            <field name="repeat_api_token" control="password">
                <rule validator="sameAs" message="system-config.sentry:api_token.match.validation.message">
                    <param name="field" value="api_token" />
                </rule>
            </field>
            <field binding="sentry.configuration_option" />
        </fieldset>
        ...
    </tab>
    ...
</form>

Param elements consist of a name and value pair and will differ for each validator.

Attributes

validator	ID of the validator to use (see Validation framework for full details on validators)
message	Message to display for validation errors. Can be an i18n resource URI for translatable validation messages.