Standard form field types/Single-page reference

Latest revision as of 10:55, 24 August 2012

This page lists all documented form field types together. Use the printable version of this page to print this reference.

[edit] Calendar form field type

The calendar form field type 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. If the field has a saved value this is shown in the text box. Otherwise the default value, if any, is displayed.

• type (mandatory) must be calendar.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default date. This must be given in the same format as specified by the format argument. You can put "NOW" to have current time.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the text box.
• readonly (optional) is whether the text box is read-only (true or false). If the text box is read-only, the date cannot be changed, but can be selected and copied. No calendar icon will be shown.
• disabled (optional) is whether the text box is disabled (true or false). If the text box is disabled, the date cannot be changed, selected or copied.
• class (optional) is a CSS class name for the HTML form field.
• format (optional) is the date format to be used. This is in the format used by PHP to specify date string formats (see below). If no format argument is given, '%Y-%m-%d' is assumed (giving dates like '2008-04-16').
• filter (optional) is time zone to be used. There are two values; server_utc and user_utc. The first one is server time zone and the later is user time zone as configured in global configuration and user information respectively.

Example XML field definition:

<field name="mycalendar" type="calendar" default="5-10-2008" label="Select a date" description="" format="%d-%m-%Y" />

The format attribute specifies the format that the date string will be saved in. It is also the format that manually entered dates need to be enterered in; except that the punctuation character is ignored. The coding scheme used to specify date formats is the same as the PHP date string format, full details of which can be found on http://www.php.net/manual/en/function.date.php. The following are some of the most frequently used date string codes:

Note: The format in which dates are stored in the params.ini file is that specified by the format argument. Since there can be language-dependent elements to this format (for example, the '%F' specifier), you need to be careful not to use such elements if there is a possibility that the front-end and back-end languages may be different.

Note: The calendar form field type does not support non-Gregorian calendars. If you need to support non-Gregorian calendars then you will need to create a custom form field type to support your calendar.

[edit] See also

• List of standard form field types

[edit] Category form field type

The category form field type provides a drop down list of all published categories for a certain extension. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected. If the show_root attribute is 1, the first option on the list will be a string representing the root category (which is a translatable string) and is given the value 0.

• type (mandatory) must be category.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• extension (mandatory) is the name of the extension for which the categories will be retrieved. For example, to list content categories, use the value 'com_content'.
• scope (optional) is an alias for extension.
• show_root (optional) is whether a choice representing the root category will be shown.
• default (optional) is the default category ID number.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'inputbox'.
• published (optional) (true/false) is whether the drop down will show only published or unpublished categories.

Example XML parameter definition:

<field name="mycategory" type="category" extension="com_content" label="Select a category" description="" />

[edit] See also

• List of standard form field types

[edit] Checkbox form field type

The checkbox form field type provides a single checkbox. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be checkbox
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• value (optional) is the value of the parameter if this checkbox is set (usually 1).
• default (optional) is the default value (usually 0 or 1).
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the label.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'inputbox'.

Example XML field definition:

<field name="show_title" type="checkbox" label="Show title" description="Show the title of the item" value="1" />

Example XML field definition (unchecked):

<field name="show_title" type="checkbox" label="Show title" description="Show the title of the item" value="1" default="0" />

Special care needs to be taken with saving a checkbox from a form!! This is a common mistake. You see, on saving a form with a checkbox that is unchecked, there is no variable for it in the POST information and joomla does not take care of that yet! See Discussion on this page for more.

[edit] See also

• List of standard form field types

[edit] Componentlayout form field type

The componentlayout form field type provides a drop down list of all available layouts for a view of an extension. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be componentlayout.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• extension (mandatory) is the name of the extension for which the layouts will be retrieved (e.g. 'com_content').
• view (mandatory) is the name of the view for which the layouts will be retrieved (e.g. 'article').
• useglobal (optional).
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML parameter definition:

<field name="mylayout" type="componentlayout" extension="com_content" view="article" label="JFIELD_ALT_LAYOUT" useglobal="true" description="JFIELD_ALT_COMPONENT_LAYOUT" />

[edit] See also

• List of standard form field types

[edit] Editor form field type

The Editor field type provides a WYSIWYG editor.

• type (mandatory) must be editor.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• width (optional) defines the width (in pixels) of the wysiwyg editor and defaults to 100%.
• height (optional) defines the height (in pixels) of the wysiwyg editor and defaults to 250px.
• cols (optional) defines the width of the editor (in columns).
• rows (optional) defines the height of the editor (in rows).
• buttons (optional) can be an array of plugin buttons to be excluded or set to false. The default editors-xtd are: article, image, pagebreak and readmore.
• hide (optional) array of plugin buttons to be hidden
• editor specifies the editor to be used and can include two options (editor="desired|alternative")
• filter (optional) allow the system to save certain html tags or raw data.

Example XML Definition

<field name="test1" label ="Test Field" type="editor" width="300" filter="safehtml" />

[edit] See also

• Textarea parameter type
• Table of all standard form field types

[edit] Editors form field type

The editors form field type provides a drop down list of the available and enabled WYSIWYG editors. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

The first option on the list is always '- Select Editor -' (which is a translatable string) and is given the value 0.

• type (mandatory) must be editors.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default editor name. This is the name listed in the File column in the Plugin Manager screen.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML parameter definition:

<field name="myeditor" type="editors" default="none" label="Select an editor" />

[edit] See also

• List of standard form field types

[edit] File form field type

Intro: todo

• type (mandatory) must be file.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) (not translatable) is the default value, but doesn't mean much for a file.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• size (optional) is the width of the file box in characters.
• accept (optional) Tells the browser what MIME types your form will allow to be uploaded.
• class (optional) is a CSS class name for the HTML form field.
• disabled (optional) HTML equivalent attribute
• onchange (optional) HTML equivalent attribute
• required (optional) For Joomla form validating it to be filled in
• validate (optional) Whether to Joomla validate the field according to rules
• onchange (optional) HTML equivalent attribute (javascript use)

Note: You should always add the attribute enctype="multipart/form-data" to your form tag when using the file input type. Otherwise, the uploaded files will not be attached correctly.

Note 2: You can put a soft limit file size by adding a hidden field with name="MAX_FILE_SIZE" and value the maximum allowed bytes which is handled by php, but you must also handle it in your code with or without it. Example XML field definition:

<field name="myfilevalue" type="file" label="Enter some text" description="Choose an image from your computer with maximum 100KB" size="10" accept="image/*" />

[edit] See also

• Media_form_field_type
• List of standard form field types

[edit] Filelist form field type

The filelist form field type provides a drop down list of files from a specified directory. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

By default, the first item on the list is '- Do not use -' (which is translatable) and is given the value '-1' and this is followed by '- Use default -' (also translatable) given the value '0'.

• type (mandatory) must be filelist.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• directory (optional) is the filesystem path to the directory containing the files to be listed. f omitted the directory given by JPATH_ROOT is assumed.
• default (optional) is the default file name.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• filter (optional) is a regular expression string which is used to filter the list of files selected for inclusion in the drop-down list. If omitted, all files in the directory are included. The filter argument expression is applied before the exclude argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• exclude (optional) is a regular expression string which is used to exclude files from the list. The exclude argument expression is applied after the filter argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• stripext (optional) is a Boolean argument. If true then file name extensions will be stripped from the file names listed. Also note that the file name will be saved without the extension too.
• hide_none (optional) is a Boolean argument. If true, the '- Do not use -' item is omitted from the drop-down list.
• hide_default (optional) is a Boolean argument. If true, the '- Use default -' item is omitted from the drop-down list.

Example XML field definition:

<field name="myfile" type="filelist" default="" label="Select a file" description="" directory="administrator" filter="" exclude="" stripext="" />

[edit] See also

• Folderlist form field type
• Imagelist form field type
• List of standard form field types

[edit] Folderlist form field type

In Joomla! 1.5, form fields were parameters. For that version, you may want to use the corresponding Folderlist parameter type.

The folderlist form field type provides a drop down list of folders from a specfied directory. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

By default, the first item on the list is '- Do not use -' (which is translatable) and is given the value '-1' and this is followed by '- Use default -' (also translatable) given the value '0'.

• type (mandatory) must be folderlist.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• directory (mandatory) is the filesystem path to the directory containing the folders to be listed.
• default (optional) is the default folder name.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• filter (optional) is a regular expression string which is used to filter the list of folders selected for inclusion in the drop-down list. If omitted, all folders in the directory are included. The filter argument expression is applied before the exclude argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• exclude (optional) is a regular expression string which is used to exclude folders from the list. The exclude argument expression is applied after the filter argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• hide_none (optional) is a Boolean argument. If true, the '- Do not use -' item is omitted from the drop-down list.
• hide_default (optional) is a Boolean argument. If true, the '- Use default -' item is omitted from the drop-down list.

Example XML field definition:

<field name="myfolder" type="folderlist" default="" label="Select a folder" directory="administrator" filter="" exclude="" stripext="" />

[edit] See also

• Filelist form field type
• Imagelist form field type
• List of standard form field types

[edit] Groupedlist form field type

The groupedlist form field type provides a drop down list or a list box of custom-defined entries which has the ability to show grouped data. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be groupedlist.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default list item value.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'inputbox'.
• multiple (optional) is whether multiple items can be selected at the same time (true or false).

The XML <field> element must include one or more <option> elements which define the list items. The text between the <option> and </option> tags is what will be shown in the drop down list and is a translatable string. The <option> tag takes the following argument:

• value (mandatory) is the value that will be saved for the field if this item is selected.

Tip: Don't forget to close the field definition with </field>.

To group the data simply put a <group> before the <option> elements you want to group and a </group> after them. The <group> tag takes the following argument:

• label (translatable) is the text shown in the list.

Example XML field definition:

<field name="mylistvalue" type="groupedlist" default="" label="Select an option" description="">
  <group label="Group 1">
    <option value="0">Option 1</option>
    <option value="1">Option 2</option>
  </group>
  <group label="Group 2">
    <option value="3">Option 3</option>
    <option value="4">Option 4</option>
  </group>
  <option value="5">Option 5</option>
  <option value="6">Option 6</option>
</field>

[edit] See also

• List form field type
• Filelist form field type
• Folderlist form field type
• Imagelist form field type
• List of standard form field types

[edit] Helpsite form field type

The helpsite form field type provides a drop down list of the help sites in your Joomla installation. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected. With the exception of the “Local” entry, which is always added, the list of help sites is generated from the file:

[path-to-Joomla]/administrator/help/helpsites-15.xml

The 'local' string is translatable. The 'local' URL returned is an empty string.

• type (mandatory) must be helpsite.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default help site URL (not the visible help site name).
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML parameter definition:

<field name="myhelpsite" type="helpsite" default="" label="Select a help site" description="" />

[edit] See also

• List of standard form field types

[edit] Hidden form field type

The hidden form field type provides a hidden field for saving a 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). If the parameter has a saved value this is entered in the text box. If not, the default value (if any) is entered. As the field is hidden there is no visible field in the Administrator.

• type (mandatory) must be hidden.
• name (mandatory) is the unique name of the field.
• default (mandatory) is the data which needs to be collected.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'text_area'.

Example XML field definition:

<field name="mysecretvariable" type="hidden" default="" />

[edit] See also

• List of standard form field types

[edit] Imagelist form field type

The imagelist form field type provides a drop down list of image files in a specified directory. Only files with .png, .gif, .jpg, .bmp, .ico extensions are listed. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

By default, the first item on the list is '- Do not use -' (which is translatable) and is given the value '-1' and this is followed by '- Use default -' (also translatable) given the value '0'.

• type (mandatory) must be imagelist.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• directory (optional) is the filesystem path to the directory containing the image files to be listed. If omitted the directory given by JPATH_ROOT is assumed.
• default (optional) is the default image file name.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• filter (optional) is a regular expression string which is used to filter the list of image files selected for inclusion in the drop-down list. If omitted, all image files in the directory are included. The filter argument expression is applied before the exclude argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• exclude (optional) is a regular expression string which is used to exclude image files from the list. The exclude argument expression is applied after the filter argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• stripext (optional) is a Boolean argument. If true then file name extensions will be stripped from the image file names listed. Also note that the file name will be saved without the extension too.
• hide_none (optional) is a Boolean argument. If true, the '- Do not use -' item is omitted from the drop-down list.
• hide_default (optional) is a Boolean argument. If true, the '- Use default -' item is omitted from the drop-down list.

Example XML field definition:

<field name="myimage" type="imagelist" default="" label="Select an image" description="" directory="" exclude="" stripext="" />

[edit] See also

• List of standard form field types

[edit] Integer form field type

The integer form field type provides a select box with a range of integer values. If the field has a value saved, this value is displayed when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be integer.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) (translatable) is the default value.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'text_area'.
• first (mandatory) this value is the lowest on the list.
• last (mandatory) this value is the highest on the list.
• step (mandatory) each option will be the previous option incremented by this integer, starting with the first value until the last value is reached.

Example XML field definition which would create a select box with the choices of 1,2,3,4,5,6,7,8,9,10:

<field name="myintegeralue" type="integer" default="Some integer" label="Choose an integer" description="" first="1" last="10" step="1" />

[edit] See also

• List of standard form field types

[edit] Language form field type

The languages form field type provides a drop down list of the installed languages for the Front-end or Back-end. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected. The value saved is the language tag. For example, for English (United Kingdom) this will be 'en-GB'.

The first option on the list is always '- Select Language -' (which is a translatable string) and is given the value 0.

• type (mandatory) must be language.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• client (mandatory) is the application whose installed languages will be listed. Use site when you want to list the Front-end languages or administrator when you want to list the Back-end languages.
• default (optional) is the default language tag. For example, 'en-GB'.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML parameter definition:

<field name="mylanguage" type="language" client="site" default="en-GB" label="Select a language" description="" />

[edit] See also

• List of standard form field types

[edit] List form field type

The list form field type provides a drop down list or a list box of custom-defined entries. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be list.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default list item value.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'inputbox'.
• multiple (optional) is whether multiple items can be selected at the same time (true or false).

The XML <field> element must include one or more <option> elements which define the list items. The text between the <option> and </option> tags is what will be shown in the drop down list and is a translatable string. The <option> tag takes the following argument:

• value (mandatory) is the value that will be saved for the field if this item is selected.

Tip: Don't forget to close the field definition with </field>.

Example XML field definition:

<field name="mylistvalue" type="list" default="" label="Select an option" description="">
  <option value="0">Option 1</option>
  <option value="1">Option 2</option>
</field>

[edit] See also

• Filelist form field type
• Folderlist form field type
• Imagelist form field type
• List of standard form field types

[edit] Media form field type

The media form field type provides modal access to the media manager for the choice of an image. Users with appropriate permissions will be able to upload files.

• type (mandatory) must be media.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• directory (mandatory) is the directory from which the user will be able to choose a file. This attribute should be relative to the top level /images/ folder.
• preview (optional) shows or hides the preview of the currently chosen image. ("true": Show always, "tooltip": Show as tooltip, "false": Show never) (since Joomla! 2.5.5)

Example XML field definition:

<field name="myimage" type="media" directory="stories" />

This will open the media manager with the directory /images/stories/ already selected.

[edit] See also

• File form field type
• Imagelist form field type
• List of standard form field types

[edit] Menu form field type

The menu form field type provides a drop down list of the available menus from your Joomla! site. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

The first option on the list is always '- Select Menu -' (which is a translatable string) and is given the value 0.

• type (mandatory) must be menu.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default menu. Note that this is the name of the menu shown in the Type column on the Menu Manager screen and not the menu ID number.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML field definition:

<field name="mymenu" type="menu" default="mainmenu" label="Select a menu" description="Select a menu" />

[edit] See also

• Menuitem form field type
• List of standard form field types

[edit] Menuitem form field type

The menuitem form field type provides a drop down grouped list of the available menu items from your Joomla site.

• type (mandatory) must be menuitem.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default menu item. Note that this is the ItemID number of the menu item.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• published (optional) determines whether all menu items are listed or only published menu items. If state is '0' then all menu items will be listed. If state is '1' then only published menu items will be listed.

To add additinal rows with translatable strings (such as "Select" or "Default") add an option to the XML. For example:

<option value="">JDEFAULT</option>

Example XML field definition:

<field name="mymenuitem" type="menuitem" default="45" label="Select a menu item" description="Select a menu item" />

[edit] See also

• Menu form field type
• List of standard form field types

[edit] Modulelayout form field type

The modulelayout form field type provides a drop down list of all available layouts for a module, grouped by core and template. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be modulelayout.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML parameter definition:

<field name="mymodulelayout" type="modulelayout" label="JFIELD_ALT_LAYOUT_LABEL" description="JFIELD_ALT_MODULE_LAYOUT_DESC" />

[edit] See also

• List of standard form field types

[edit] Note form field type

This article is for Joomla! CMS Version(s)

This form field makes it possible to create titles, texts, descriptions and even alert boxes. It also allows you to bring order in the settings for extensions, by separating them with useful titles. Or adding descriptions for certain settings (without having to rely on the tooltips). Or adding any other text you want.

The syntax is pretty straight-forward:

<field name="..." type="note" label="..." description="..." class="..." close="..." />

[edit] Attributes

• Name: contains the name of the field (like with any other field tag)
• Type: the type of the field, which is: note
• Label: the title of the note (uses JText) (optional if using description)
• Description: the description/text of the note (uses JText) (optional if using label)
• Heading: the type of heading element to use for the label (optional) (default: h4)
• Class: a class name (or class names), like alert (see further for examples) (optional)
• Close: a value of 'true' (for alerts) or the value for the data-dismiss of the bootstrap close icon (optional)

[edit] Title and or Description

In the following code examples we will use these example language strings:

LOREMIPSUM="Lorem ipsum dolor sit amet"
LOREMIPSUM_DESC="Consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat."

So with this note field you can either use the title or the description or both.

<field name="opt10" type="text" label="Some Other Option" />
<field name="note11" type="note" label="LOREMIPSUM" />
<field name="opt11" type="text" label="Some Other Option" />
<field name="note12" type="note" description="LOREMIPSUM_DESC" />
<field name="opt12" type="text" label="Some Other Option" />
<field name="note13" type="note" label="LOREMIPSUM" description="LOREMIPSUM_DESC" />
<field name="opt13" type="text" label="Some Other Option" />

[edit] Classes (Alerts)

You can add classes to the note. This way you can make (bootstrap) alerts very easily. But also any other styling via class names you want (like a 'well').

<field name="opt20" type="text" label="Some Other Option" />
<field name="note21" type="note" class="alert" label="LOREMIPSUM" description="LOREMIPSUM_DESC" />
<field name="opt21" type="text" label="Some Other Option" />
<field name="note22" type="note" class="alert alert-info" label="LOREMIPSUM" description="LOREMIPSUM_DESC" />
<field name="opt22" type="text" label="Some Other Option" />
<field name="note23" type="note" class="alert alert-success" label="LOREMIPSUM" description="LOREMIPSUM_DESC" />
<field name="opt23" type="text" label="Some Other Option" />
<field name="note24" type="note" class="alert alert-error" label="LOREMIPSUM" description="LOREMIPSUM_DESC" />
<field name="opt24" type="text" label="Some Other Option" />

[edit] Close button

A close button can be added to the alerts by adding the close="true" attribute to the tag. If you use a different class than the alert, use the required value for the data-dismiss of the bootstrap close icon instead of the value "true". But here is the code to test the close icon on an alert.

<field name="opt30" type="text" label="Some Other Option" />
<field name="note31" type="note" class="alert" close="true" label="LOREMIPSUM" description="LOREMIPSUM_DESC" />
<field name="opt31" type="text" label="Some Other Option" />

[edit] See also

• List of standard form field types

[edit] Password form field type

The password form field type provides a text box for entry of a password. The password characters will be obscured as they are entered. If the field has a saved value this is entered (in obscured form) into the text box. If not, the default value (if any) is entered.

Note that the password string is stored in params.ini in cleartext; the stored value is not obscured by any hash function. Since most web servers will, by default, serve a params.ini file if the URL is entered in a web browser, this cannot be considered a secure method of holding a password.

• type (mandatory) must be password.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• size (optional) is the width of the text box in characters. If omitted the width is determined by the browser. The value of size does not limit the number of characters that may be entered.
• default (optional) is the default password.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'text_area'.

Example XML field definition:

<field name="mypassword" type="password" default="secret" label="Enter a password" description="" size="5" />

[edit] See also

• Text form field type
• List of standard form field types

[edit] Radio form field type

The radio form field type provides radio buttons to select different options. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be radio.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default radio button item value.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

The XML <field> element must include one or more <option> elements which define the individual radio button items. The text between the <option> and </option> tags is shown as the label for the radio button and is a translatable string. The <option> tag takes the following argument:

• value (mandatory) is the value that will be saved for the parameter if this item is selected.

Tip: Don't forget to close the field definition with </field>.

Example XML field definition:

<field name="myradiovalue" type="radio" default="0" label="Select an option" description="">
  <option value="0">1</option>
  <option value="1">2</option>
</field>

[edit] See also

• List form field type
• List of standard form field types

[edit] Rules form field type

The rules parameter type provides a matrix of group by action options for managing access control.

• type (mandatory) must be rules.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• component (mandatory) indicates the component to which the action options will apply.
• section (mandatory) indicates the section of the access.xml actions the control should apply to. For example, "component" or "my_item_type".

[edit] See also

• Table of all standard form field types

[edit] SQL form field type

The sql form field type provides a drop down list of entries obtained by running a query on the Joomla database. If the field has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be sql.
• name (mandatory) is the unique name of the field. This must match the name of the query results column that contains the values that will be shown to the user in the drop-down list, unless a different name is specified in the value_field attribute.
• label (mandatory) (translatable) is the descriptive title of the field.
• query (mandatory) is the SQL query which will provide the data for the drop-down list. The query must return two columns; one called 'value' (unless overridden by the key_field attribute) which will hold the values of the list items; the other called the same as the value of the name attribute (unless overridden by the value_field attribute) containing the text to be shown in the drop-down list.
• default (optional) is the default value. This is the value of the 'value' field, unless overridden by the key_field attribute.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• key_field (optional) is the name of the column that will contain values for the parameter. If omitted then the column called 'value' will be used, if it exists.
• value_field (optional) is the name of the column that will contain values to be shown to the user in the drop-down list. If omitted then the column with the same name as the name attribute will be used, if it exists.
• translate (optional) will translate the output of the value_field if set to true. It defaults to false.

Example XML parameter definition:

<field name="title" type="sql" default="10" label="Select an article" query="SELECT id AS value, title FROM #__content" />

Notice that an AS clause has been used in this example because the jos_content table does not have a column called 'value'. In fact very few tables in the Joomla database have a column called 'value'. Alternatively, you can use a key_field attribute to define the column to be instead of 'value':

<field name="title" type="sql" default="10" label="Select an article" query="SELECT id, title FROM #__content" key_field="id" />

This will give identical results to the previous example.

Both column names may need to be aliased. For example, suppose you want your field to be called 'myfield' instead of 'title' in the previous example. Then you can do this:

<field name="myfield" type="sql" default="10" label="Select an article" query="SELECT id AS value, title AS myfield FROM #__content" />

Or alternatively:

<field name="myfield" type="sql" default="10" label="Select an article" query="SELECT id, title FROM #__content" key_field="id" value_field="title" />

You can also assemble or calculate fields in the SQL statement. For example, suppose you wanted to append the created date/time of each article to the article title in the list. Then you could use this SQL statement:

SELECT id, concat( title, ' (', created, ')') AS title FROM #__content

Note: The SQL statements will need to be correct for the type and version of the underlying database that Joomla is running on. This will most likely be a version of MySQL, but it could be something else. There is no capability to query databases other than the one Joomla itself is running on.

Note: As shown in these examples, the database prefix (often jos) should be entered in the form #_ (hash-underscore). It will automatically be replaced by the actual database prefix used by Joomla.

[edit] See also

• List of standard form field types

[edit] Spacer form field type

The spacer form field type provides a visual separator between parameter field elements. It is purely a visual aid and no field value is stored.

• type (mandatory) must be spacer.
• name (mandatory?) is the unique name of the field.
• label (optional) (translatable) is the text to use as a spacer.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• hr (optional) is whether to display a horizontal rule ('true' or 'false'). If this attribute is 'true', the label attribute will be ignored.
• class (optional) is a CSS class name for the HTML form field.

Example XML field definition:

<field type="spacer" name="myspacer" hr="true" />

You can replace the basic horizontal line with a title which can be used to group parameters. For example,

<field type="spacer" name="myspacer" label="Advanced parameters" />

You can also place translatable text into the label attribute:

<field type="spacer" name="myspacer" class="text"
label="PLG_TINY_FIELD_NAME_EXTENDED_LABEL"
/>

Note that you can also include HTML markup but it must be encoded. For example, to put the text into bold you can use:

<field type="spacer" name="myspacer" label="&lt;b&gt;Advanced parameters&lt;/b&gt;" />

You cannot combine the hr and label attributes. To define a spacer with both a horizontal rule and a label, use an encoded <hr/> in the label attribute:

<field type="spacer" name="myspacer" label="&lt;hr/&gt;More parameters" />

[edit] See also

• List of standard form field types

[edit] Tag form field type

The Tag field type provides a point where you can enter tags - this is either AJAX or nested.

• type (mandatory) must be tag.
• name (mandatory) is the unique name of the parameter.
• mode (optional) (translatable) is the description of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• description (optional) (translatable) is the description of the field.
• id (optional) is the id to add to the field. Note if none is set this will be the name of the field.
• class (optional) is the class to add to the field.
• published (optional) determines if non published tags should be allowed.
• language (optional) is language to filter the existing tags by.
• multiple (optional) is the ability to add more than 1 tag to the form field.
• custom (optional) if the ajax mode is chosen setting this to deny will prevent users from adding in new tags.

Example XML Definition for an AJAX Tag

<field name="tags" type="tag" label="JTAG" description="JTAG_DESC" mode="ajax" class="inputbox span12 small" multiple="true" />

Example XML Definition for an Nested Tag

<field name="tags" type="tag" label="JTAG" description="JTAG_DESC" mode="nested" class="inputbox span12 small" multiple="true" />

[edit] See also

Joomla! Community Magazine April 2013 Issue

[edit] Text form field type

The text form field type provides a text box for data entry. If the field has a value saved, this value is displayed when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be text.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• size (optional) is the width of the text box in characters. If omitted the width is determined by the browser. The value of size does not limit the number of characters that may be entered.
• maxlength (optional) limits the number of characters that may be entered.
• default (optional) (not translatable) is the default value.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'text_area'.
• readonly (optional)
• disabled (optional)
• filter (optional) allow the system to save certain html tags or raw data.

Example XML field definition:

<field name="mytextvalue" type="text" default="Some text" label="Enter some text" description="" size="10" />

Use the integer filter to ensure that letters types get stripped when the form is processed.

<field name="myintvalue" type="text" default="8" label="Enter some text" description="Enter some description" filter="integer" />

Use the raw filter to ensure that html code is preserved when the form is processed.

<field name="myhtmlvalue" type="text" default="" label="Enter some text" description="Enter some description" filter="raw" />

[edit] See also

• Textarea form field type
• List of standard form field types

[edit] Textarea form field type

The textarea form field type provides a text area for entry of multi-line text. If the field has a value saved, this value is displayed when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be textarea.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• rows (mandatory) is the height of the visible text area in lines. If omitted the width is determined by the browser. The value of rows does not limit the number of lines that may be entered.
• cols (mandatory) is the width of the visible text area in characters. If omitted the width is determined by the browser. The value of cols does not limit the number of characters that may be entered.
• default (optional) (not translatable) is the default value.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'text_area'.
• filter (optional) allow the system to save certain html tags or raw data.

Example XML field definition:

<field name="mytextarea" type="textarea" default="default" label="Enter some text" description="" rows="10" cols="5" />

Use the raw filter to ensure that html code is preserved when the form is processed:

<field name="mytextarea" type="textarea" default="default" label="Enter some html" description="" rows="10" cols="5" filter="raw"/>

[edit] Tips

• If you need to line break just encode <br /> in the XML config file like this: <br />
• If you need a new line character in your default value, add 
 to the default parameter

[edit] See also

• Text form field type
• List of standard form field types

[edit] Timezone form field type

The timezones form field type provides a drop down list of time zones. If the field has a value saved, this value is displayed when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be timezone.
• name (mandatory) is the unique name of the field.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) (translatable) is the default time zone. For example, use '-10' for '(UTC -10:00) Hawaii'.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML field definition:

<field name="mytimezone" type="timezone" default="-10" label="Select a timezone" description="" />

[edit] See also

• List of standard form field types

[edit] User form field type

This article is a stub and needs to be expanded. If you can provide information or finish this article you're welcome to do so. Please remove this message afterwards or replace with {{inuse}} while making major edits. - Thank you.

The user form field type provides a modal select box of users.

• type (mandatory) must be user.
• name (mandatory) is the unique name of the field. This must match the name of the query results column that contains the values that will be shown to the user in the drop-down list, unless a different name is specified in the value_field attribute.
• label (mandatory) (translatable) is the descriptive title of the field.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field.
• size (optional) is the width of the text box in characters. If omitted the width is determined by the browser. The value of size does not limit the number of characters that may be entered.

Example user form field definition:

   <field name="title" type="user" label="Select a user" />

[edit] See also

• List of standard form field types

[edit] Usergroup form field type

This article is a stub and needs to be expanded. If you can provide information or finish this article you're welcome to do so. Please remove this message afterwards or replace with {{inuse}} while making major edits. - Thank you.

The usergroup form field type provides a modal select box of user groups.

• type (mandatory) must be usergroup.

• name (mandatory) is the unique name of the field. This must match the name of the query results column that contains the values that will be shown to the user in the drop-down list, unless a different name is specified in the value_field attribute.

• label (mandatory) (translatable) is the descriptive title of the field.

• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

• class (optional) is a CSS class name for the HTML form field.

• size (optional) is the width of the text box in characters. If omitted the width is determined by the browser. The value of size does not limit the number of characters that may be entered.

Example user form field definition:

   <field name="title" type="usergroup" label="Select a user group" />

[edit] See also

• List of standard form field types