Actions

Standard form field types/Single-page reference

From Joomla! Documentation

< Standard form field types
Revision as of 10:55, 24 August 2012 by Mvangeest (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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

Accesslevel form field type

provides a dropdown list of accesslevel options with the current option selected.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be accesslevel.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description description text for the form field.
  • class additional classes to set style.

Implemented by: libraries/joomla/form/fields/access.php function: level

Example XML Definition

<field name="access" type="accesslevel"
        label="JFIELD_ACCESS_LABEL"
        description="JFIELD_ACCESS_DESC"
        class="span12 small" />

Cachehandler form field type

provides a list of available cache handling options.

  • type (mandatory) must be cachehandler.
  • name (mandatory) is the unique name of the parameter.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description description text for the form field.
  • filter filter to apply, normally use "word".

Example XML Definition

<field name="cache_handler"
        type="cachehandler"
        default=""
        label="COM_CONFIG_FIELD_CACHE_HANDLER_LABEL"
        description="COM_CONFIG_FIELD_CACHE_HANDLER_DESC"
        filter="word">
</field>

Calendar form field type

Params.calendar.jpg

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:

Character Description Example
d Day of the month, 2 digits with leading zeros 01 to 31
D A textual representation of a day, three letters Mon through Sun
j Day of the month without leading zeros 1 to 31
l A full textual representation of the day of the week Monday through Sunday
N ISO-8601 numeric representation of the day of the week (only supported on servers running PHP 5.1.0 or later) 1 (for Monday) through 7 (for Sunday)
S English ordinal suffix for the day of the month, 2 characters st, nd, rd or th. Works well with j
w Numeric representation of the day of the week 0 (for Sunday) through 6 (for Saturday)
z The day of the year (starting from 0) 0 through 365
W ISO-8601 week number of year, weeks starting on Monday 42 (42nd week in the year)
F A full textual representation of a month January through December
m Numeric representation of a month, with leading zeros 01 through 12
M A short textual representation of a month, three letters Jan through Dec
n Numeric representation of a month, without leading zeros 1 through 12
t Number of days in the given month 28 through 31
o ISO-8601 year number. Same value as Y except that if the ISO week number (W) belongs to the previous or next year, that year is used instead (only supported on servers running PHP 5.1.0 or later) 1999 or 2003
Y A full numeric representation of a year, 4 digits 1999 or 2003
y A two-digit representation of a year 99 or 03
a Lowercase Ante Meridiem or Post Meridiem am or pm
A Uppercase Ante Meridiem or Post Meridiem AM or PM

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.

See also

Captcha form field type

provides a drop down list of the captcha plugins.

  • type (mandatory) must be plugins.
  • name (mandatory) is the unique name of the field.
  • folder (mandatory) must be captcha.
  • 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 Definition

<field name="captcha" type="plugins" folder="captcha"
        label="COM_CONTACT_FIELD_CAPTCHA_LABEL"
        description="COM_CONTACT_FIELD_CAPTCHA_DESC"
        default="" 
        filter="cmd" >
        <option value="">JOPTION_USE_DEFAULT</option>
        <option value="0">JOPTION_DO_NOT_USE</option>
</field>

Category form field type

Params.category.jpg

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.

Implemented by libraries/legacy/form/field/category.php.

Example XML parameter definition:

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

See also

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" />
Stop hand nuvola.svg.png
Warning!

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.


See also

Checkboxes form field type

The checkboxes form field type provides a set of checkboxes. Note: unlike most standard form field types, such as textfield or checkbox, this field is not an "out of the box" solution. It will create checkboxes for you, and submit their values in form of an array, but it will not store them in the database.

Example:

<field name="toppings" type="checkboxes">
    <option value="anch">Anchovies</option>
    <option value="chor">Chorizo</option>
    <option value="on">Onions</option>
    <option value="mush">Mushrooms</option>
</field>

The set of checkboxes can be generated in your form with a single statement like this:

<?php echo $this->form->getInput('toppings'); ?>

This will generate the following HTML, which can be styled using CSS:

<fieldset id="jform_toppings" class="checkboxes">
        <ul>
                <li><input type="checkbox" id="jform_toppings0"
                        name="jform[toppings][]" value="anch" /><label for="jform_toppings0">Anchovies</label></li>
                <li><input type="checkbox" id="jform_toppings1"
                        name="jform[toppings][]" value="chor" /><label for="jform_toppings1">Chorizo</label></li>
                <li><input type="checkbox" id="jform_toppings2"
                        name="jform[toppings][]" value="on" /><label for="jform_toppings2">Onions</label></li>
                <li><input type="checkbox" id="jform_toppings3"
                        name="jform[toppings][]" value="mush" /><label for="jform_toppings3">Mushrooms</label></li>
        </ul>
</fieldset>

If the user checks the second and fourth item and submits the form, the Joomla server will provide the following result:

print_r(JRequest::getVar('jform')['toppings']) =>
 
Array
(
    [0] => chor
    [1] => mush
)

ChromeStyle form field type

provides a dropdown list of style options with the current option selected.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be chromestyle.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description description text for the form field.


Example XML Definition

<field name="style" type="chromestyle"
        label="COM_MODULES_FIELD_MODULE_STYLE_LABEL"
        description="COM_MODULES_FIELD_MODULE_STYLE_DESC" />

Color form field type

Provides a color picker. Enter the color as #ff00ff or pick it from the palet.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be chromestyle.
  • default (optional) provides a color when not set.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description (optional) (translatable) tooltip for the form field.


Example XML Definition

<field name="backgroundcolor" type="color" default="#eee"
        label="TPL_BEEZ3_FIELD_HEADER_BACKGROUND_COLOR_LABEL"
        description="TPL_BEEZ3_FIELD_HEADER_BACKGROUND_COLOR_DESC" />

Combo form field type

Provides a combobox field.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be combobox.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description (optional) (translatable) tooltip for the form field.
  • class (optional) specify your own classes for additonal markup, defaults to "combobox"
  • readonly (optional) set to "true", defaults to false, meaning editable.
  • disabled (optional) set to "true", defaults to false, meaning enabled.
  • size (optional) sets the input size of the field
  • required (optional) sets whether input is required, defaults to no input required.
<field name="myeditbox" type="combobox" label="MyEditBox" description="myeditbox_Desc" size="7" />

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" />

See also

ContentLanguage form field type

Provides a list of content languages..

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be text.
  • label (mandatory) is the descriptive title of the field.
  • description (optional) tooltip for the form field.

Example XML Definition from plugins/system/languagecode/languagecode.php

if ($languages = JLanguage::getKnownLanguages(JPATH_SITE))
{
        // Inject fields into the form
        foreach ($languages as $tag => $language)
        {
                $form->load('
                        <form>
                                <fields name="params">
                                        <fieldset
                                                name="languagecode"
                                                label="PLG_SYSTEM_LANGUAGECODE_FIELDSET_LABEL"
                                                description="PLG_SYSTEM_LANGUAGECODE_FIELDSET_DESC"
                                        >
                                                <field
                                                        name="'.strtolower($tag).'"
                                                        type="text"
                                                        description="' . htmlspecialchars(JText::sprintf('PLG_SYSTEM_LANGUAGECODE_FIELD_DESC', $language['name']), ENT_COMPAT, 'UTF-8') . '"
                                                        translate_description="false"
                                                        label="' . $tag . '"
                                                        translate_label="false"
                                                        size="7"
                                                        filter="cmd"
                                                />
                                        </fieldset>
                                </fields>
                        </form>
                ');
        }
}

Contentlanguage form field type

provides a list of installed content languages for use in conjunction with the language switcher plugin.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be contentlanguage.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description (optional) (translatable) tooltip for the form field.


Example XML Definition

<field name="language" type="contentlanguage"
        label="JFIELD_LANGUAGE_LABEL"
        description="COM_CATEGORIES_FIELD_LANGUAGE_DESC"
        class="span12 small" >
        <option value="*">JALL</option>
</field>

Contenttype form field type

Provides a list of content types.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be contenttype.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description (optional) (translatable) tooltip for the form field.


Example XML Definition

<field name="types" type="contenttype"
        label="COM_TAGS_FIELD_TYPE_LABEL"
        description="COM_TAGS_FIELD_TYPE_DESC"
        multiple="true" />

DatabaseConnection form field type

Provides a list of available database connections, optionally limiting to a given list.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be contentlanguage.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description (optional) (translatable) tooltip for the form field.


Example XML Definition

<field name="dbtype" type="databaseconnection"
        label="COM_CONFIG_FIELD_DATABASE_TYPE_LABEL"
        description="COM_CONFIG_FIELD_DATABASE_TYPE_DESC"
        supported="mysql,mysqli,postgresql,sqlsrv,sqlazure"
        filter="string" />

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. eg... set buttons="true" hide="readmore,pagebreak"
  • 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" />


See also

Editors form field type

Params.editors.jpg

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" />

See also

Email form field type

provides an input field for an email address.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be email.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description description text for the form field.
  • size (optional) determines the size of the field on the screen.
  • required (optional) "true" to enforce a value.
  • class (optional) for styling.
  • validate (optional) makes sure it is an emailaddress.

Example XML Definition

<field name="email" type="email"
        label="JGLOBAL_EMAIL"
        description="COM_ADMIN_USER_FIELD_EMAIL_DESC"
        required="true"
        size="30"
        class="inputbox"
        validate="email" />

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/*" />


See also

Filelist form field type

Params.filelist.jpg

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="" />

See also

Folderlist form field type

Params.folderlist.jpg
Info non-talk.png
General Information

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="" />


See also

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>

See also

HeaderTag form field type

provides a dropdown list of h1 to h6 as options.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be headertag.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description description text for the form field.
  • default (optional) provides a default value.

Example XML Definition

<field name="header_tag" type="headertag"
        label="COM_MODULES_FIELD_HEADER_TAG_LABEL"
        description="COM_MODULES_FIELD_HEADER_TAG_DESC" 
        default="h3"/>

Helpsite form field type

Params.helpsites.jpg

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="" />

See also

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="" />

See also

Imagelist form field type

Params.imagelist.jpg

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="" />

See also

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="myintegervalue" type="integer" default="Some integer" label="Choose an integer" description="" first="1" last="10" step="1" />

See also

Language form field type

Params.language.jpg

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="" />

See also

List form field type

Params.list.jpg

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>

See also

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.

See also

Menu form field type

Params.menu.jpg

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" />

See also

Menuitem form field type

Params.menuitem.jpg

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" />


See also

ModuleOrder form field type

Provides a drop down to set the ordering of module in a given position.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be moduleorder.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description (optional) (translatable) tooltip for the form field.

Example XML Definition

<field name="ordering" type="moduleorder"
        label="JFIELD_ORDERING_LABEL" 
        description="JFIELD_ORDERING_DESC" />

ModulePosition form field type

provides a text input to set the position of a module.

  • type (mandatory) must be moduleposition.
  • 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.

Example XML Definition

<field name="position" type="moduleposition"    
        description="COM_MODULES_FIELD_POSITION_DESC"
        label="COM_MODULES_FIELD_POSITION_LABEL"
        default=""
        maxlength="50" />

ModuleTag form field type

provides a list of html5 elements (used to wrap a module in).

  • type (mandatory) must be moduletag.
  • 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.

Example XML Definition

<field name="module_tag" type="moduletag"
        label="COM_MODULES_FIELD_MODULE_TAG_LABEL"
        description="COM_MODULES_FIELD_MODULE_TAG_DESC"
        default="div" />

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" />

See also

Note form field type

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="..." />

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)

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" />

Help25-note-form-field-title-screenshot.png

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" />

Help25-note-form-field-classes-screenshot.png

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" />

Help25-note-form-field-close-screenshot.png


See also

Password form field type

Params.password.jpg

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" />

See also

Plugins form field type

provides a dropdown list of plugin options from the folder.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be plugin.
  • folder (mandatory) editor or captcha.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description description text for the form field.


Example XML Definition

<field name="editor" type="plugins" folder="editors"
        description="COM_USERS_USER_FIELD_EDITOR_DESC"
        label="COM_USERS_USER_FIELD_EDITOR_LABEL" >
        <option value="">JOPTION_USE_DEFAULT</option>
</field>

Radio form field type

Params.radio.jpg

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>

See also

Repeatable form field type

Provides a modal with rows of formfields that you specify. As many options can be added as desired. Note this form field has a jQuery based javascript file as a dependency.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be repeatable.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description description text for the form field. Displays at the top of the modal with the name as well as in the usual position in the form
  • default The default value for the form field if the field is left empty. Note this has to be a json string compatible with the contents of the form field.
  • id id of the hidden from field. (the modal will have this id with an added suffix of "_modal" and the table within the modal will have this id with a suffix of _modal_table")
  • class class of the table.
  • select (translatable) The text to show on the modal button.
  • icon the icon to show on the select button (is prefixed with "icon-").
  • maximum the maximum number of rows of fields allowed (by default 999 to be effectively infinite)

To create a form field you must first of all create a repeatable form field as usual. Within this you place

<fields>

open and close tag (if not already in one - if there is an existing fields tag for params etc. this is not needed.) and within this a

<fieldset>

tag. The fieldset tag MUST have a name the same as your repeatable field name with "_modal" appended to the end of it - it should also have the

repeat="true"

in the fieldset tag. Within this fieldset you then include the form fields that you wish to have repeating (as with any form field).

Example XML Definition

<field name="list_templates"
        type="Repeatable"
        icon="list"
        description="PLG_TINY_FIELD_TEMPLATE_FIELD_ELEMENTS_DESC"
        label="PLG_TINY_FIELD_TEMPLATE_FIELD_ELEMENTS_LABEL"
        default="{'template':['Layout','Simple snippet'],'location':['layout1.html','snippet1.html'],'description':['HTMLLayout','Simple HTML snippet']}">
        <fields name="params">
        <fieldset hidden="true" name="list_templates_modal" repeat="true">
                <field name="template"
                        label="PLG_TINY_FIELD_TEMPLATE_FIELD_NAME_LABEL"
                        size="30"
                        type="text" />
                <field name="location"
                        label="PLG_TINY_FIELD_TEMPLATE_FIELD_LOCATION_LABEL"
                        description="PLG_TINY_FIELD_TEMPLATE_LOCATION_DESC"
                        size="30"
                        type="filelist"
                        directory="media/editors/tinymce/templates"
                        exclude="index.html"
                        hide_default="true"
                        hide_none="true" />
                <field name="description"
                        label="PLG_TINY_FIELD_TEMPLATE_FIELD_DESCRIPTION_LABEL"
                        size="30"
                        type="textarea" />
        </fieldset>
        </fields>
</field>

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".

See also

SQL form field type

Params.sql.jpg
Stop hand nuvola.svg.png
Warning!

Using this generic form field type forces you to write SQL in an XML file and is rather limited. For more flexibility, consider creating your own, specific form field type by subclassing the JFormField class.


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 used 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

You can also specify static option in the XML using <option></option> tag. Please look at the following example.

<field name="myfield" type="sql" default="10" label="Select an article" query="SELECT id, title FROM #__content" key_field="id" value_field="title" required="true">
<option value="">Please select your option</option>
</field>

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-underscore). It will automatically be replaced by the actual database prefix used by Joomla.

See also

Sessionhandler form field type

provides a dropdown list of session handler options.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be sessionhandler.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description description text for the form field.
  • default (optional) provides a default value.
  • required (optional) "true" to enforce a value.
  • filter (optional) cleans the input.

Example XML Definition

<field name="session_handler" type="sessionhandler"
        default="none"
        label="COM_CONFIG_FIELD_SESSION_HANDLER_LABEL"
        description="COM_CONFIG_FIELD_SESSION_HANDLER_DESC"
        required="true"
        filter="word" />

Spacer form field type

Params.spacer.jpg

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" />

See also

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" />


See also

Joomla! Community Magazine April 2013 Issue

Templatestyle form field type

provides a dropdown list of style options.

  • name (mandatory) is the unique name of the parameter.
  • type (mandatory) must be templatestyle.
  • client (optional) administrator, defaults to site.
  • label (mandatory) (translatable) is the descriptive title of the field.
  • description description text for the form field.
  • class (optional) for styling.

Example XML Definition

<field name="admin_style" type="templatestyle"
        client="administrator"
        description="COM_ADMIN_USER_FIELD_BACKEND_TEMPLATE_DESC"
        label="COM_ADMIN_USER_FIELD_BACKEND_TEMPLATE_LABEL" >
                <option value="">JOPTION_USE_DEFAULT</option>
</field>

Text form field type

Params.text.jpg

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) The field cannot be changed and will automatically inherit the default value
  • disabled (optional) The field cannot be changed and will automatically inherit the default value - it will also not submit
  • required (optional) The field must be filled before submitting the form.
  • filter (optional) allow the system to save certain html tags or raw data.
  • message (optional) The error message that will be displayed instead of the default message.

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" />

See also

Textarea form field type

Params.textarea.jpg

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"/>

Tips

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

See also

Timezone form field type

Params.timezones.jpg

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="" />

See also

URL form field type

This field essentially is a text field with the type of url. If a fully qualified url (that is one with a scheme and domain such as http://example.com) is entered and it uses idn (that is uses characters that are non ascii such as ê or Ψ) it will translate the url into punycode prior to saving. This assures that the url will work as intended regardless of environment. If you want to render field data in idn you should wrap it with the conversion method

JStringPunycode::urlToUTF8($this->contact->webpage)

.

  • type (mandatory) must be url.
  • 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) The field cannot be changed and will automatically inherit the default value
  • disabled (optional) The field cannot be changed and will automatically inherit the default value - it will also not submit
  • required (optional) The field must be filled before submitting the form.
  • filter (optional) allow the system to save certain html tags or raw data.

Example XML field definition:

<field name="mytextvalue" type="url" default="http://www.example.com" label="Enter a URL" description="" size="10" />


Both a url rule and a url input filter can assist with this insuring that valid url data are entered into this field field

See also

User form field type

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.

Implemented by: libraries/cms/form/field/user.php

Example user form field definition:

<field name="modified_user_id" type="user"
        label="JGLOBAL_FIELD_MODIFIED_BY_LABEL"
        class="readonly"
        readonly="true"
        filter="unset" />

See also

Usergroup form field type

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.
  • multiple (optional) If set to multiple then allows more than one usergroup to be selected.

Implemented by: libraries/joomla/form/fields/usergroup.php

Example user form field definition:

<field name="guest_usergroup" type="usergroup"
        label="COM_USERS_CONFIG_FIELD_GUEST_USER_GROUP_LABEL"
        description="COM_USERS_CONFIG_FIELD_GUEST_USER_GROUP_DESC" 
        multiple="true" />


See also