XML Form Headers

XML Form Headers

Unlike form fields, the header fields only apply to Browse forms. A header field has two distinct functions:

• It is used to render headers in list views which are used to label the columns of the display and optionally allow you to sort the table by a specific field

• It is used to render filtering widgets (drop-down lists and search boxes). The filtering widgets are rendered either above the header fields (search boxes) or in the sidebar (drop-down lists). You can have as many filter fields as you want, even more than the number of fields you are displaying in the filter list.

A header form field can render only a header, only a filter or both depending on its attributes.

Common attributes

Common attributes for all fields

You can use the following attributes in all header fields:

name The name of the header field. This has to match the table field name in the model.

If you want to create a header for a calculated field or for a column that doesn't correspond to a table field please use a name that isn't the same as any column in the database table. If you want to use the same field multiple times (e.g. display a row selection checkbox and the record ID at the same time) you will have to use the same name in both headers, but use a different id attribute.

type The header field type. See below for the available field types, as well as the options which can be specified in each one of them.

label The language string which will be used for the label of the header; this is a language string that will be fed to JText::_() for translation.

If none is provided FOF will automatically create one using the convention component_modelname_fieldname_LABEL where component is the name of your component, modelname is the name of your model (usually equals to the view name) and fieldname is the name of the field. For example, for a component com_foobar, a view named items and a field named baz we get the language string COM_FOOBAR_ITEMS_BAZ_LABEL.

id The id attribute for this header. Skip it to have FOF create one based on the field name.

tdwidth The width of this column in the list table. You can use percentile or pixel units, i.e. tdwidth="10%" or tdwidth="120px"

sortable Set to true if you want to be able to sort the table by this field. If you set it to false only a header label will be shown but you won't be able to sort by this field.

filterclass The CSS class for the filter (search box or drop-down list) widget

onchange The Javascript code to be executed when the filter widget's value is modified

onlyFilter When set to true only a filter (search or drop-down list) widget will be rendered. A table header column will NOT be generated. Use it for filter-only header fields in your forms.

Additional attributes for search box filtering widgets

The following attributes apply to all header fields rendering a search box filtering widget:

searchfieldname The name of the input element of the filter widget. Use it to have the filter value have a different name than the field name. If omitted it will be the same as the name attribute.

placeholder The placeholder text when the field is empty. Useful to explain what kind of information this search field is supposed to be searching in.

size The size (in characters) of the search box

maxlength The maximum length in characters which is allowed to be entered in the field

buttons Set to true (or do not specify) to show Search and Reset buttons next to the text field. Set to false to hide those buttons. The user can still press Enter to submit the form.

buttonclass The CSS class of the Search and Reset buttons

Additional attributes for drop-down list filtering widgets

This element has <option> sub-elements defining the available options. Please consult Joomla!'s own list field type for more information.

The following optional attributes can be specified for all fields which support drop-downs. They allow you to specify a programmatic source for the options instead of hard-coding them in your XML form. These attributes apply to all form types.

source_file (optional) The PHP file which provides the class and method. It is given in the pseudo-URL format e.g. admin://components/com_foobar/helpers/mydata.php or site://components/com_foobar/helpers/mydata.php for a file relative to the administrator or site root directory respectively. You do NOT need to use this attribute for auto-loaded classes, e.g. Helper classes of any FOF-powered component.

source_class (required) The fully qualified name of the PHP class to use, e.g. \Acme\Example\Admin\Helper\Select

source_method (required) The static method of the PHP class to use, e.g. getSomeFoobarData.

The method must accept no parameters and must return either an array of indexed arrays or an options object generated by JHtml.

source_format (optional) The format of the returned data of the static method. Set to optionsobject if the method returns a pre-generated options object. Do not set this attribute if you return an array of indexed arrays.

source_key (optional) If you are returning an array of indexed arrays, this is the key of the indexed array that contains the key of the drop-down option.

source_value (optional) If you are returning an array of indexed arrays, this is the key of the indexed array that contains the value (description) of the drop-down option.

source_translate (optional) By default all values are fed through JText::_(). If you don't want that, set this attribute to "false".

Header field types

Please note that the pages linked from this list only contain the attributes specific to each field type. For the common attributes please look above.

• AccessLevel
• Date
• Field
• Filterable
• Language
• Model
• Ordering
• Published
• RowSelect
• Searchable
• Selectable
• SelectRow
• Sql