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

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 value argument of the <option> tag is the value that will be saved for the field if this item is selected. Don't forget to close the field definition with </field>.

XML Field Definition

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

Add first an option without a value, with a text like "Select an option". Otherwise, in case of a required field, the first option with a value gets silently selected (without the user choosing it). This text will typically be seen by users before clicking the drop down list.

Mandatory Parameters

  1. type must be list.
  2. name is the unique name of the field.
  3. label (translatable) is the descriptive title of the field.

Optional Parameters

  1. default is the default list item value.
  2. description (translatable) is help text.
  3. class is a CSS class name for the HTML form field.
  4. multiple is whether multiple items can be selected at the same time (true or false).
  5. required: if set to true, the first field option should be empty.
  6. useglobal: if set to true, it will show the value that is set in the global configuration if found in the database.
  7. layout: Use list-fancy-select layout to provide search option in the list.

Examples

1. Display Offline Message (Global Configuration)

<field
 name="display_offline_message"
 type="list"
 label="COM_CONFIG_FIELD_SITE_DISPLAY_MESSAGE_LABEL"
 default="1"
 filter="integer"
 showon="offline:1"
 validate="options">
  <option value="0">JHIDE</option>
  <option value="1">COM_CONFIG_FIELD_VALUE_DISPLAY_OFFLINE_MESSAGE_CUSTOM</option>
  <option value="2">COM_CONFIG_FIELD_VALUE_DISPLAY_OFFLINE_MESSAGE_LANGUAGE</option>
 </field>

2. State Field (com_content)

<field
 name="state"
 type="list"
 label="JSTATUS"
 class="form-select-color-state"
 default="1"
 validate="options">
  <option value="1">JPUBLISHED</option>
  <option value="0">JUNPUBLISHED</option>
  <option value="2">JARCHIVED</option>
  <option value="-2">JTRASHED</option>
</field>

3. Show Title Field (com_content)

<field
 name="show_title"
 type="list"
 label="JGLOBAL_SHOW_TITLE_LABEL"
 useglobal="true"
 validate="options">
  <option value="1">JSHOW</option>
  <option value="0">JHIDE</option>
</field>