forms

Show pagesource Old revisions Recent changes

Form XML Reference

Form XML Reference

The XML used to define forms is divided into two fundamental groups. There is the definition of the form itself including it's structure, and the definition of form input fields and their labels.

XML Heirarchy

form
- name
- method
- action
- group
  - name
  - label
  - switch
    - ...
  - field
    - ...
- switch
  - depends
  - case
    - target
    - group
      - ...
    - switch
      - ...
    - field
      - ...
  - default
    - group
      - ...
    - switch
      - ...
    - field
      - ...
- field
  - name
  - label
  - type
  - value
  - options
    - option
      - label
      - value
  - validate
    - type
    - rule
      - type

These tags are used to define a form and organize its contents. Every form must be contained within a single <form> tag. Groups are optional, but recommended for larger forms as it will allow for a view have greater control over how the form is displayed (allowing for pagination or some other form of logical separation).

Note: Any attributes marked in bold are required.

`FORM`	Description
	The main container for a form. All other tags should be defined within this tag.
	Subtags
	`group`, `field`, `switch`
	Attribute	Type	Possible Values	Description
	`name`	string	*	A unique identifier for the form.
	`method`	string	[“get”, “post”]	The method used to submit the form.
	`action`	string	*	The URL to which the form will be submitted.

`GROUP`	Description
	A container for related input fields.
	Subtags
	`field`, `switch`
	Attribute	Type	Possible Values	Description
	`name`	string	*	A unique identifier for the group.
	`label`	string	*	An optional label to display with the group.

`SWITCH`	Description
	A container for related cases that are dependent on the value of a given field.
	Subtags
	`case`, `default`
	Attribute	Type	Possible Values	Description
	`depends`	string	*	The name of the field on which the switch depends.

`CASE`	Description
	Contains all fields to be displayed if the dependent field is set to the case's target value.
	Subtags
	`group`, `field`, `switch`
	Attribute	Type	Possible Values	Description
	`target`	string	*	The value to match against the dependent field.

`DEFAULT`	Description
	The default case if none of the defined cases are matched.
	Subtags
	`group`, `field`, `switch`

Input Definition & Labels

The following tags are used to define form input fields. Fields of different types will have different combinations of allowable attributes and subtags. See the type reference to determine which subtags and attributes are used for a specific field type.

Note: Any attributes marked in bold are required.

`FIELD`	Description
	An input field for the form.
	Subtags
	`options`, `validate`
	Attribute	Type	Possible Values	Description
	`name`	string	*	A unique identifier for the field.
	`label`	string	*	An optional label to display with the field.
	`type`	string	(see field types)	The type of field.
	`value`	string	*	The field's default value.

`OPTIONS`	Description
	A container for input field options. This is used where possible values are chosen from a predefined list.
	Subtags
	`option`

`OPTION`	Description
	A specific value for a multi-value input field. This tag should always be defined within the `OPTIONS` tag.
	Attribute	Type	Possible Values	Description
	`label`	string	*	A label for the option.
	`value`	string	*	A value for the option.

`VALIDATE`	Description
	A container for validation rules that apply to the parent field.
	Subtags
	`rule`
	Attribute	Type	Possible Values	Description
	`type`	string	(see validation types)	The type of validation to perform.

`RULE`	Description
	Specifies a validation rule. Any contained text will be used as a failure message to the user.
	Attribute	Type	Possible Values	Description
	`type`	string	(see rule types)	The type of rule to apply.

Field Types

Out of the box, Bedrock supports a wide variety of basic form field types (listed below). Types are stored within namespaces that logically group related fields together. Currently there are two official namespaces: std which holds types that closely match those defined in the HTML spec, and adv which holds more complex types.

Field types are managed in a way that allows them to be extensible. You can easily define custom field types and namespaces that meet your specific needs. For more information on how to add your own field types, see the field_types area of the Extending Bedrock section.

Type	Declaration	Description
`std`
Text	`std:text`	Accepts standard text input.
Password	`std:password`	Accepts standard text input, but masks typed text.
Hidden	`std:hidden`	A hidden field usually preset or assigned with JavaScript.
Checkbox	`std:checkbox`	Simple checkbox field.
Radio Button	`std:radio`	Simple radio button field.
Dropdown Selection	`std:select`	Dropdown selection list.
Multi-Checkbox	`std:multicheck`	List with multiple checkboxes.
Multi-Radio Button	`std:multiradio`	List with multiple radio buttons.
File	`std:file`	Simple file selection field.
Image	`std:image`	Simple image selection field.
Button	`std:button`	Standard button.
Submit Button	`std:submit`	Standard submit button.
Reset Button	`std:reset`	Standard reset button.
`adv`
Date	`adv:date`	Date input field (M,D,Y).
Date & Time	`adv:datetime`	Date & time input field (M,D,Y,H,m,s).
Time	`adv:time`	Time input field (H,m,s,).
Timezone	`adv:timezone`	Timezone selection field.
Product Key	`adv:key`	Product serial key field.
SSN	`adv:ssn`	Social security number field.

Validation & Rule Types

Validation and validation rule types are used to affect how submitted forms are processed on a field-by-field basis.

Validation Types

Currently, there are three validation types supported:

submit will apply the contained validation rules after the form has been submitted (server side).
ajax will apply the validation rules once the field loses focus and return a success or failure (with message) (client side).
both will use both methods, which is the default and is recommended for most cases.

A validation type is defined as an attribute within a <validate> tag:

<validate type="submit"> 
    ... 
</validate>

Rule Types

A comprehensive collection of validation rules come built-in and are listed below. There are two built-in namespaces, std and adv, which both contain some standard and some more advanced rules respectively.

In addition to these base rules, custom rules are also possible. To learn more about writing your own custom validation rules, see the rules area of the Extending Bedrock section.

Type	Declaration	Description
`std`
Required	`std:required`	The field must contain a value.
Numeric	`std:numeric`	Only numeric characters are allowed.
Alphabetic	`std:alphabetic`	Only alphabetic characters are allowed.
Alphanumeric	`std:alphanumeric`	Only alphanumeric characters are allowed.
Maximum Length	`std:maxlength`	The field's value cannot exceed a certain length.
Minimum Length	`std:minlength`	The field's value must be at least a certain length.
Match	`std:match`	The value must match the value of another field.
Like	`std:like`	The value must be similar to a certain string.
Whitelist	`std:whitelist`	Only values among a specific list are allowed.
Blacklist	`std:blacklist`	Any values not in a specific list are allowed.
Email	`std:email`	The field must contain a valid email address.
Phone Number	`std:phone`	The field must contain a valid phone number.
Postal Code	`std:postalcode`	The field must contain a valid postal code.
Matched Password	`std:password`	The two typed passwords must match.
`adv`
Username In Use	`adv:username`	The username cannot already be in use or disallowed.
Strong Password	`adv:password`	The password must a specific degree of strength.