The filelist form field 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'.

Example XML field definition:

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

Mandatory Parameters

  • type must be filelist.

  • name is the unique name of the field.

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

Optional Parameters

  • directory is the filesystem path to the directory containing the files to be listed. If omitted the directory given by JPATH_ROOT is assumed.

  • default is the default file name.

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

  • filter 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.

  • exclude 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.

  • stripext is a Boolean argument. If true then file name extensions will be stripped from the file names listed. The file name will be saved without the extension too.

  • hide_none is a Boolean argument. If true, the '- None selected -' item is omitted from the drop-down list.

  • hide_default is a Boolean argument. If true, the '- Use default -' item is omitted from the drop-down list.