Form field
From Joomla! Documentation
Introduction
Form fields are fields in a HTML <form>. Joomla! 2.5 and newer supply the JForm class to conveniently and flexibly create forms with a many form fields. Each form field type is a subclass of JFormField.
In addition to being a flexible page creation tool, JFormFields are used by Joomla! to allow Administrators to configure Joomla! or its extensions without changing the underlying code. In Joomla! 1.5, this was handled by the now deprecated JParameter and JElement classes.
To define form fields in the configuration of an extension, you must include them in a named fieldset, such as <fieldset name="basic">, that is within the <fields name="params"> section of the <config> element in your XML manifest file.
Form Validation
Joomla has client-side and server-side form validation capabilities.
Server side validation is essential since everything before that can be overridden on the user side by hackers. However client-side is the most user-friendly validation, so using both is considered best practice.
Client-side validation
.. is done via javascript while the user is filling in the form fields.
It uses the HTML classes required and validate-[xxx] (with [xxx] being a joomla or custom rule; e.g. validate-numeric)
More here: Client-side form validation
Server-side validation
.. is done after having submitted the form and will normally return to the form when not validated with some extra messages.
It uses the HTML attributes required ("true" or "required") and validate (with value being a joomla or custom rule; e.g. validate="email")
More here: Server-side form validation
Standard Form Field Types
Numerous types of form field are built into Joomla!. The following table lists these standard types and their availability. Use the single-page reference if you want to print all existing form field documentation.
Please note that many of these fields are available as parameter types in Joomla! 1.5. For a list of parameter types, see J1.5:Standard parameter types. For a comparison between form field and parameter types, see Standard form field and parameter types.
Type | Description | Availability | |
---|---|---|---|
accessiblemedia | provides modal access to the media manager for insertion of images with upload for users with appropriate permissions and a text field for adding a alternative text. | ![]() | |
accesslevel | provides a drop down list of viewing access levels. | ![]() | |
cachehandler | provides a list of available cache handling options. | ![]() | |
calendar | provides a text box for entry of a date. An icon next to the text box provides a link to a pop-up calendar, which can also be used to enter the date value. | ![]() | |
captcha | provides the use of a captcha plugin. | ![]() | |
category | provides a drop down list of categories for an extension. | ![]() | |
checkbox | provides a single checkbox to be checked or unchecked | ![]() | |
checkboxes | provides unlimited checkboxes that can be used for multi-select. | ![]() | |
Chrome Style | provides a list of template chrome style options grouped by template. | ![]() | |
color | provides a color picker when clicking the input box. | ![]() | |
Content Language | Provides a list of content languages. | ![]() | |
Content Type | Provides a list of content types. | ![]() | |
combo | provides a combo box field. | ![]() | |
componentlayout | provides a grouped list of core and template alternative layouts for a component item. | ![]() | |
contentlanguage | provides a list of installed content languages for use in conjunction with the language switcher plugin. | ![]() | |
Database Connection | Provides a list of available database connections, optionally limiting to a given list. | ![]() | |
editor | provides an editor area field. | ![]() | |
editors | Provides a drop down list of the available WYSIWYG editors. Since ![]() |
![]() | |
provides an email field. | ![]() | ||
file | Provides an input field for files | ![]() | |
filelist | provides a drop down list of files from a specified directory. | ![]() | |
folderlist | provides a drop down list of folders from a specified directory. | ![]() | |
groupedlist | provides a drop down list of items organized into groups. | ![]() | |
header tag | provides a drop down list of the header tags (h1-h6). | ![]() | |
helpsite | provides a drop down list of the help sites for your Joomla installation. | ![]() | |
hidden | provides a hidden field for saving a form field whose value cannot be altered directly by a user in the Administrator (it can be altered in code or by editing the params.ini file). | ![]() | |
imagelist | provides a drop down list of image files in a specified directory. | ![]() | |
integer | provides a drop down list of integers between a minimum and maximum. | ![]() | |
language | provides a drop down list of the installed languages for the Front-end or Back-end. | ![]() | |
list | provides a drop down list of custom-defined entries. | ![]() | |
media | provides modal access to the media manager for insertion of images with upload for users with appropriate permissions. | ![]() | |
menu | provides a drop down list of the available menus from your Joomla site. | ![]() | |
Menu Item | provides a drop down list of the available menu items from your Joomla site. | ![]() | |
meter | Provides a meter to show value in a range. | ![]() | |
Module Layout | provides a list of alternative layout for a module grouped by core and template. | ![]() | |
Module Order | Provides a drop down to set the ordering of module in a given position | ![]() | |
Module Position | provides a text input to set the position of a module. | ![]() | |
Module Tag | provides a list of html5 elements (used to wrap a module in). | ![]() | |
note | supports a one line text field. | ![]() | |
number | Provides a one line text box with up-down handles to set a number in the field. | ![]() | |
password | provides a text box for entry of a password. The password characters will be obscured as they are entered. | ![]() | |
plugins | provides a list of plugins from a given folder. | ![]() | |
predefinedlist | Form Field to load a list of predefined values. | ![]() | |
radio | provides radio buttons to select different options. | ![]() | |
range | Provides a horizontal scroll bar to specify a value in a range. | ![]() | |
repeatable | Allows form fields which can have as many options as the user desires. | ![]() | |
rules | provides a matrix of group by action options for managing access control. Display depends on context. | ![]() | |
sessionhandler | provides a drop down list of session handler options. | ![]() | |
spacer | provides a visual separator between form fields. It is purely a visual aid and no value is stored. | ![]() | |
sql | provides a drop down list of entries obtained by running a query on the Joomla Database. The first results column returned by the query provides the values for the drop down box. | ![]() | |
subform | provides a way to use XML forms inside each other or reuse your existing forms inside your current form. | ![]() | |
tag | provides an entry point for tags (either AJAX or Nested). | ![]() | |
tel | provides an input field for a telephone number. | ![]() | |
templatestyle | provides a drop down list of template styles. | ![]() | |
text | provides a text box for data entry. | ![]() | |
textarea | provides a text area for entry of multi-line text. | ![]() | |
timezone | provides a drop down list of time zones. | ![]() | |
URL | provides a URL text input field. | ![]() | |
user | Field to select a user from a modal list. Displays User Name and stores User ID | ![]() | |
useractive | Field to show a list of available user active statuses. | ![]() |
|
usergroup | provides a drop down list of user groups. Since ![]() |
![]() |
|
usergrouplist | Field to load a drop down list of available user groups. Replaces usergroup form field type. | ![]() |
|
userstate | Field to load a list of available users statuses. | ![]() |
Custom Form Field Types
An extension can define its own form field types that can then be used in its own forms or forms created by another extension. See Creating a custom form field type for instructions.
Modal Form Field Types
If you have a field with many values that don't fit a selection box, you can always make a modal form field that will allow the user to pick an item from a modal page with a table, filtering options, etc. (Just like any administrator table, e.g. "Articles".) See Creating a modal form field
Common Attributes
Labelclass
Adding the attribute labelclass adds a CSS class for form field's label. Source: http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=28450
Showon
Adding the attribute showon allows you to hide the field based on the value(s) of another field.
The syntax to show the field bar only when foo is set to "1" and baz is set to "1":
<field
name="foo"
type="list"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
<field
name="bar"
type="text"
showon="foo:1"
/>
To match multiple values one can provide a comma-separated list of values such as showon="foo:1,2"
To combine multiple fields, use [AND] as in showon="foo:1[AND]bar:1"
The syntax to show the field bar only when foo is set to "1" and baz is set to "1":
<field
name="foo"
type="list"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
<field
name="baz"
type="list"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
<field
name="bar"
type="text"
showon="foo:1[AND]baz:1"
/>
To create a choice among multiple fields, use [OR] as in showon="foo:1[OR]bar:1".
The syntax to show the field bar only when foo is set to "1" or baz is set to "1":
<field
name="foo"
type="list"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
<field
name="baz"
type="list"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
<field
name="bar"
type="text"
showon="foo:1[OR]baz:1"
/>
You can also use value 'does not equal' as in showon="field1!:1".
The syntax to show the field bar only when foo is not equal to "1":
<field
name="foo"
type="list"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
<field
name="baz"
type="list"
showon="foo!:1"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
To show a field when another field (e.g. foo) has been selected (when that other field is not empty), use showon="foo!:" (without a value specified).
This was introduced with a pull request, available starting with Joomla 3.2.4.
Troubleshooting: Attributes Not Working
If you have read an older version of our developer documentation, or took your form display code from an existing extension, you may be experiencing issues with attributes like showon not working at all. In order for some special attributes to function, your fields must be rendered using their renderField() method. For example:
<div class="row-fluid">
<div class="span6">
<?php
foreach($this->form->getFieldset() as $field) {
echo $field->renderField();
}
?>
</div>
</div>