Field types
Form element type, can be a text field, a select (dropdown), radio (radio group), checkbox.
Text
By far the most prevalent type of form element is the text element, allowing for limited text entry;
it's an ideal element for most data entry.
Textarea
Textareas are used when large quantities of text are expected, and place no limits on the amount of text submitted (other than maximum size limits as dictated by your server or PHP).
Example: This configuration shows how to create a text area and set the number of rows and columns.
<phone_code> <!-- Field name (from Fields and join tab) -->
<type>textarea</type> <!-- Field type -->
<options>
<label>Phone code</label> <!-- Display name (parsed through translate file) -->
<rows>10</rows> <!-- Number of rows -->
<cols>10</cols> <!-- Number of columns -->
</options>
</phone_code>
Checkbox
HTML checkboxes allow you return a specific value, but basically operate as booleans.
By default, the checked value is '1', and the unchecked value '0'.
You can specify the values to use using the checkedValue and uncheckedValue properties, respectively.
Internally, any time you set the value, if the provided value matches the checked value, then it is set, but any other value causes the unchecked value to be set.
Example: This configuration shows how to create a checkbox that will set the value to "t" if checked and "f" if unchecked.
<active> <!-- Field name (from Fields and join tab) -->
<type>checkbox</type> <!-- Field type -->
<options>
<label>Active</label> <!-- Display name (parsed through translate file) -->
<checkedValue>t</checkedValue> <!-- Checked value (parsed through translate file) -->
<uncheckedValue>f</uncheckedValue> <!-- Unchecked value (parsed through translate file) -->
</options>
</active>
Gtmulticheckbox
When you want to save multiple user choices in a database text field you can use this element.
It collects checked values in a string separating them with a comma followed by space ", ".
By default, this element registers an InArray validator which validates against the array keys of registered options.
You can set the list of values by specifying them directly in the configuration file or by accessing a table in the database.
Example: This configuration shows how to create a gtmulticheckbox that will read and set options from the database.
<building_types> <!-- Field name (from Fields and join tab) -->
<type>gtmulticheckbox</type> <!-- Field type -->
<options>
<label>Building types</label> <!-- Display name (parsed through translate file) -->
<database> <!-- Populate multiOptions from database -->
<table>building_types</table> <!-- Table name -->
<id>id</id> <!-- Key field name -->
<name>building_type</name> <!-- Value field name -->
</database>
</options>
</building_types>
Select
Select boxes are a common way of limiting to specific choices for a given form datum.
By default, this element registers an InArray validator which validates against the array keys of registered options.
You can set the list of values by specifying them directly in the configuration file or by accessing a table in the database.
Example 1: In this example we will create a list of predefined values for a select field. Values are from the configuration file itself. As a result user will see a list of country names for field phone_code populated from value and key will bet set in the database.
<phone_code> <!-- Field name (from Fields and join tab) -->
<type>select</type> <!-- Field type -->
<options>
<label>Phone code</label> <!-- Display name (parsed through translate file) -->
<multiOptions>
<md> <!-- Option name (arbitrary) -->
<key>373</key> <!-- Option key -->
<value>Moldova</value> <!-- Option value -->
</md>
<ua>
<key>380</key>
<value>Ukraine</value>
</ua>
</multiOptions>
</options>
</phone_code>
Example 2: In this example we will create a list of predefined values for a select field.
Values are populated from the database table.
The database table can be created by uploading a dbf file (single file no .shx or .shp) using the tutorials.admin.database.pkg section of the Administrator panel.
As a result user will see a list of country names for field phone_code populated from field "name" of country_name table and "id" will bet set in the database.
<phone_code> <!-- Field name (from Fields and join tab) -->
<type>select</type> <!-- Field type -->
<options>
<label>Phone code</label> <!-- Display name (parsed through translate file) -->
<database> <!-- Populate multiOptions from database -->
<table>countries_codes</table> <!-- Table name -->
<id>country_code</id> <!-- Key field name -->
<name>country_name</name> <!-- Value field name -->
</database>
</options>
</phone_code>
Now the editing form will display the select box values as intended, but Information, Search and other tools show the field "id" not "name".
This can be fixed in the Fields and joins section by creating a join rule between the table countries_codes and your main table.
Gtmultiselect
When you want to save multiple user choices in a database text field you can use this element.
It collects selected values in a string separating them with a comma followed by space ", ".
XHTML select elements allow a 'multiple' attribute, indicating multiple options may be selected for submission, instead of the usual one.
By default, this element registers an InArray validator which validates against the array keys of registered options.
You can set the list of values by specifying them directly in the configuration file or by accessing a table in the database.
In the example below we will create a list of predefined values for a select field. Values are populated from the database table.
<building_types> <!-- Field name (from Fields and join tab) -->
<type>gtmultiselect</type> <!-- Field type -->
<options>
<label>Building types</label> <!-- Display name (parsed through translate file) -->
<database> <!-- Populate multiOptions from database -->
<table>building_types</table> <!-- Table name -->
<id>id</id> <!-- Key field name -->
<name>building_type</name> <!-- Value field name -->
</database>
</options>
</building_types>
Radio
Radio elements allow you to specify several options, of which you need a single value returned.
You can set the list of values by specifying them directly in the configuration file or by accessing a table in the database.
<type>radio</type> <!-- Field type -->
Options are the same as for Select.
File
The File form element provides a mechanism for supplying file upload fields to your form.
Example: This configuration shows how to create a file element with a specified number and size limit, also indicating file extension.
<photo> <!-- Field name (from Fields and join tab) -->
<type>file</type> <!-- Field type -->
<options>
<label>photo</label> <!-- Display name (parsed through translate file) -->
<validators>
<!-- First validator -->
<count>
<validator>Count</validator> <!-- Counts how many files should be received -->
<options>
<files>1</files> <!-- Number of files to be received -->
</options>
</count>
<!-- Second validator -->
<filessize>
<validator>FilesSize</validator> <!-- Limits the size of the uploading file -->
<options>
<min>1</min> <!-- Minimum file size -->
<max>2MB</max> <!-- Maximum file size -->
</options>
</filessize>
<!-- Third validator -->
<ext>
<validator>Extension</validator> <!-- Receives files only with specified extensions -->
<options>
<extension>jpg,png,gif</extension> <!-- List of extensions separated by comma -->
</options>
</ext>
</validators>
</options>
</photo>
Date
This element can be used to specify a certain date of year.
It uses a standart text field and enhances it with a calendar for an easier date selection.
<!-- Field name (from Fields and join tab) -->
date <!-- Field type -->
Install date <!-- Display name (parsed through translate file) -->
Validators
A validator examines its input with respect to some requirements and produces a boolean result - whether the input successfully validates against the requirements.
If the input does not meet the requirements, a validator may additionally provide information about which requirement(s) the input does not meet.
For example a field must be between six and twelve characters in length and may only contain alphanumeric characters. A validator can be used for ensuring that fields meet these requirements.
If a chosen field does not meet one or both of the requirements, it would be useful to know which of the requirements the field fails to meet.
<validators>
<!-- First validator -->
<strlen612> <!-- Validator name (arbitrary) -->
<validator>StringLength</validator> <!-- Validator class name -->
<options> <!-- Options -->
<min>6</min> <!-- "min" option with value 6 -->
<max>12</max> <!-- "max" option with value 12 -->
</options>
<breakChainOnFailure>1</breakChainOnFailure>
</strlen612>
<!-- Second validator -->
<alphanum> <!-- Validator name (arbitrary) -->
<validator>Alnum</validator> <!-- Validator class name -->
</alphanum>
</validators>
breakChainOnFailure will the validator to break the chain execution upon failure, which avoids running any other validations that are determined to be unnecessary or inappropriate for the situation.
Alnum
Returns TRUE if and only if value contains only alphabetic and digit characters.
Between
Returns TRUE if and only if value is between the minimum and maximum boundary values.
The comparison is inclusive by default (value may equal a boundary value), though this may be overridden in order to do a strict comparison, where value must be strictly greater than the minimum and strictly less than the maximum.
<myBetween> <!-- Validator name (arbitrary) -->
<validator>Between</validator> <!-- Validator class name -->
<options> <!-- Options -->
<min>0</min> <!-- "min" option with value 0 -->
<max>100</max> <!-- "max" option with value 100 -->
</options>
</myBetween>
GreaterThan
Returns TRUE if and only if value is greater than the minimum boundary.
<gt> <!-- Validator name (arbitrary) -->
<validator>GreaterThan</validator> <!-- Validator class name -->
<options> <!-- Options -->
<min>5</min> <!-- "min" option with value 5 -->
</options>
</gt>
InArray
InArray allows you to validate if a given value is contained within an array.
It is also able to validate multidimensional arrays.
<inarray> <!-- Validator name (arbitrary) -->
<validator>InArray</validator> <!-- Validator class name -->
<options> <!-- Options -->
<haystack> <!-- Array of available values -->
<key1>up</key1>
<key2>down</key2>
<key3>left</key3>
</haystack>
</options>
</inarray>
Int
Returns TRUE if and only if value is a valid integer.
Example: Create an integer validator.
If the value is not an integer then a validation note will appear and the user will be prompted to enter a value that represents a number.
<integer> <!-- Validator name (arbitrary) -->
<validator>Int</validator> <!-- Validator class name -->
</integer>
LessThan
Returns TRUE if and only if value is less than the maximum boundary.
<lt> <!-- Validator name (arbitrary) -->
<validator>LessThan</validator> <!-- Validator class name -->
<options> <!-- Options -->
<max>5</max> <!-- "max" option with value 5 -->
</options>
</lt>
StringLength
Returns TRUE if and only if the string length of value is at least a minimum and no greater than a maximum (when the max option is not NULL).
Example: Create a string lenght validator. If the length of text entered by the user is more than 80 characters then a validation note will appear and the user will be prompted to introduce valid data.
<strlen> <!-- Validator name (arbitrary) -->
<validator>StringLength</validator> <!-- Validator class name -->
<options> <!-- Options -->
<max>100</max> <!-- "max" option with value 100 -->
</options>
</strlen>
Filters
In the physical world, a filter is typically used for removing unwanted portions of input, and the desired portion of the input passes through as filter output (e.g., coffee).
In such scenarios, a filter is an operator that produces a subset of the input.
This type of filtering is useful for removing illegal input, trimming unnecessary white space, etc.
This basic definition of a filter may be extended to include generalized transformations upon input.
A common transformation applied in web applications is the escaping of HTML entities.
For example, if a form field is automatically populated with untrusted input (e.g., from a web browser), this value should either be free of HTML entities or contain only escaped HTML entities, in order to prevent undesired behavior and security vulnerabilities.
To meet this requirement, HTML entities that appear in the input must either be removed or escaped.
Of course, which approach is more appropriate depends on the situation.
A filter that removes the HTML entities operates within the scope of the first definition of filter - an operator that produces a subset of the input.
A filter that escapes the HTML entities, however, transforms the input (e.g., "&" is transformed to "&").
<filters>
<!-- First filter -->
<ent> <!-- Filter name (arbitrary) -->
<filter>HtmlEntities</filter> <!-- Filter class name -->
</ent>
<!-- Second filter -->
<trim> <!-- Filter name (arbitrary) -->
<filter>StringTrim</filter> <!-- Filter class name -->
</trim>
</filters>
StringTrim
Returns the string value with characters stripped from the beginning and end.
<trim> <!-- Filter name (arbitrary) -->
<filter>StringTrim</filter> <!-- Filter class name -->
</trim>
HtmlEntities
This filter is useful in preventing user-supplied text from containing HTML markup.
Returns the string value, converting characters to their corresponding HTML entity equivalents where they exist.
<ent> <!-- Filter name (arbitrary) -->
<filter>HtmlEntities</filter> <!-- Filter class name -->
</ent>
HTMLPurifier
Returns the string value with malicious html code filtered out.
<purify> <!-- Filter name (arbitrary) -->
<filter>HTMLPurifier</filter> <!-- Filter class name -->
</purify>
See filter classes for a complete list.