====== 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 Definition & Structure ===== These tags are used to define a form and organize its contents. Every form must be contained within a single ''
'' 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 ^^^^ | | ''[[forms#group|group]]'', ''[[forms#field|field]]'', ''[[forms#switch|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 ^^^^ | | ''[[forms#field|field]]'', ''[[forms#switch|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 ^^^^ | | ''[[forms#case|case]]'', ''[[forms#default|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 ^^^^ | | ''[[forms#group|group]]'', ''[[forms#field|field]]'', ''[[forms#switch|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 ^^^^ | | ''[[forms#group|group]]'', ''[[forms#field|field]]'', ''[[forms#switch|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 ^^^^ | | ''[[forms#options|options]]'', ''[[forms#validate|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 [[forms#field_types|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 ^^^^ | | ''[[forms#option|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 ^^^^ | | ''[[forms#rule|rule]]'' |||| | ^ Attribute ^ Type ^ Possible Values ^ Description ^^^^ | | ''type'' | string | (see [[forms#validation_types|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 [[forms#rule_types|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 [[Docs:Extending Bedrock:Forms#field_types]] area of the [[Docs: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 '''' tag: ... ==== 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 [[Docs:Extending Bedrock:Forms#rules]] area of the [[Docs: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. |