Joomla Forms and Form Fields

Many attributes map straight to HTML (size, maxlength, rows, cols, readonly, disabled, autofocus, onchange, data-*). The Manual explains the less obvious ones, and the base class FormField::__set documents the general set. The table summarises the attributes a component author uses constantly.

Since Joomla 4 the supported way to create a Form is the form factory service, FormFactoryInterface, rather than Form::getInstance(). A form needs a name that is unique among the forms on the page and an options array whose most important key is control, the prefix of the input names:

Source: Joomla Manual: How forms work

loadFile() reads the XML into a SimpleXMLElement and calls load(); both accept $reset / $replace (when a field with the same group and name already exists, true replaces it and false keeps the old one) and an $xpath to import only a part of the document. The com_menus component uses $xpath to add menu-item options from layout XML files. In code that is not inside a model you can obtain the factory from the container, Factory::getContainer()->get(FormFactoryInterface::class), but constructor injection (see Namespaces, autoloading and dependency injection) is better, and MVCFactory already hands every model a form factory.

Older tutorials and the Joomla 3-era JForm examples write JForm::getInstance('sample', $path, ['control' => 'myform']). Form::getInstance() still exists and works, and the Manual’s sample components use it, but it keeps instances in a static cache keyed by name, which makes tests and multiple instances awkward. The J* class aliases are available only through the Behaviour - Backward Compatibility 6 plugin in 6.x, so new code should import the namespaced class.

bind($data) stores an array or object inside the Form instance. At render time the stored value for a field name overrides the default attribute. setValue($name, $group, $value) changes a single value after binding and is the right tool when a plugin must force a value, because changing the default attribute would be overridden by bound data.

Source: Joomla Manual: Manipulating forms

renderField() produces a label, an input and a wrapping <div> using the joomla.form.renderfield layout, which a template can override. Remember that the output must sit inside a <form> element with method="post" and a submit control; a form object renders fields, not the form tag.

Form::process($data) is the one-call version of the server-side pipeline, and it is what FormModel::validate() calls:

A direct use, outside a model, looks like this (it is the pattern the Manual’s sample components use):

Source: Joomla Manual: How forms work

Two details matter. validate() returns true or false and puts \Exception objects into getErrors(); it throws a RuntimeException for a disabled field that was nevertheless posted, and it adds an error for a value that arrives for a field that is not part of the rendered form. That second check is a deliberate defence against mass-assignment: the server refuses data that the form definition would never have produced.

text is the base for most input types and takes size, maxlength, hint, pattern, autocomplete, inputmode and dirname. number and range accept min, max and step; integer generates a list of options from first to last with a step, which is a select, not a text input. Joomla 6.0 also made note a form field: a read-only block of formatted text that can carry a heading, a description and the close button, useful for explaining a group of options inside an administrator screen without writing a layout.

Type email automatically adds validate-email for client-side checking and, with validate="email", the server-side rule. Type telephone has no built-in server filter; use filter="tel" and validate="tel" explicitly.

calendar is the long-standing date picker. It has format (a strftime-style pattern), showtime, timeformat, todaybutton, weeknumbers, filltable, minyear and maxyear, and a filter attribute whose special values user_utc and server_utc convert a date from the user’s or the server’s time zone to UTC on save. That conversion is why a re-displayed form after a validation error needs the filtered value of a calendar field: the controller applies the filter before storing posted data back in the session.

Joomla 6.0 added two more, based on the browser’s native pickers: date (<input type="date">, with min and max in Y-m-d form) and datetime (<input type="datetime-local">, with min, max and a filter). In the source both classes are marked @since 6.0.0. They suit simple "closed from" dates such as the Tallpine closure period, while calendar is still the right choice when you need the Joomla time-zone filters, a custom format or the picker’s today and clear buttons. Older books written for Joomla 3, 4 or 5, including the Joomla 5 development book Developing Extensions for Joomla! 5 (Packt, 2023), predate these two types and know only calendar.

category lists categories of one extension (extension="com_tallpine"), accepts published, language, action (only categories on which the user has an ACL action such as core.create), show_root and allowAdd for the inline "create new" option. tag is a fancy-select tag input with mode="ajax" or mode="nested", custom="allow" and multiple. user renders a modal user picker and usergrouplist and accesslevel render group and level selectors. Most of these hit the database or ACL; they need the correct component context, which is why the same XML works in the administrator edit form, a custom field and a module parameter.

media opens the Media Manager (see Media Manager) with types, preview, directory and schemes attributes; Joomla 6.1 added audio, video and document variants of the media field, described in the custom-fields page. accessiblemedia adds the alternative-text and caption inputs. file is a real <input type="file"> that requires enctype="multipart/form-data" on the <form>, an accept attribute for the browser and server-side checks with the upload helper; Joomla does not validate the file contents for you. editor renders the editor selected by the user or by the field’s editor attribute, with buttons, hide and filter.

sql builds a list from a query. It takes query, key_field and value_field, and Joomla runs the query without placeholders, so the XML author, not the user, must control it. ordering shows items in a sort order and needs the table name and the order column. A sql field whose query contains the current user’s input is an injection hole: write a custom ListField with a bound query instead (see below).

A custom filter is a class that implements Joomla\CMS\Form\FormFilterInterface, which has a single method. Tallpine uses one to normalise the free-text alias of a trail:

Source: Joomla Manual: Standard form field attributes

The filter value TrailAlias is resolved as <prefix>\TrailAliasFilter, because the loader appends Filter to the name. The $input argument is the whole posted data set as a Registry, which lets a filter read other fields, as above. Filters must be pure: they are called again whenever a controller needs the processed data of a failed submission.

The shortest rule extends Joomla\CMS\Form\FormRule and sets $regex. This one accepts a GPX file name for the Tallpine gpx-file field:

Source: Joomla Manual: Server-side validation

FormRule::test() wraps the expression in non-printable delimiters, adds the u modifier when PCRE has Unicode properties, and returns true when preg_match succeeds. An empty $regex throws an UnexpectedValueException.

When a regular expression is not enough, implement test(). The signature, in the 6.2 source, is test(\SimpleXMLElement $element, $value, $group = null, ?Registry $input = null, ?Form $form = null). Return true for a valid value and false otherwise. The rule below checks that a trail’s elevation gain is plausible for its distance, using another field of the form; it also demonstrates reading a custom attribute from the XML element and setting a dynamic message.

Source: Joomla Manual: Server-side validation

The rule name is resolved the same way as filters: Elevation becomes <prefix>\ElevationRule. The Manual’s own example uses validate="custom" and CustomRule; the name is just a convention. The $group argument is the field-name group, so with a group bar and a field foo the HTML name is bar[foo]. In a form that nests field groups, read other fields from $input with their dotted path (params.show_map), because $input is a Registry.

A rule that must query the database follows the DI route. Because the form loader injects the database into any rule that implements DatabaseAwareInterface, the class only has to use the trait:

Source: Joomla Manual: Server-side validation

Notice the prepared statement: the posted title is never concatenated into the SQL. See Joomla database API for the query builder and Security in extensions for the injection checklist.

The pipeline order is fixed: filter, then validate. A filter can therefore mask an invalid value (an intarray filter turns abc into an empty list that required then rejects, but integer turns abc into 0, which may pass). Validation sees what the filter produced, so choose a filter that does not hide errors you want to report, and let a rule reject what a filter cannot repair.

The validator is a function registered with document.formvalidator.setHandler; the class on the field is validate- plus the handler name. This one rejects Tallpine trail codes that are not of the form TP-123:

Source: Joomla Manual: Client-side validation

The view then calls $wa->useScript('com_tallpine.validate-trail-code'). The data-validation-text attribute supplies the message. Always pair a custom JavaScript validator with a server-side rule that enforces the same constraint (here a regex rule), because the JavaScript is optional for an attacker.

The simplest and most useful custom field extends ListField and overrides getOptions(). The Tallpine difficulty grades come from a fixed list, translated, with a "choose a grade" placeholder:

Source: Joomla Manual: Example custom fields

The Manual’s Custom3Field follows the same shape with array_merge(parent::getOptions(), $options), and its Custom4Field extends GroupedlistField and overrides getGroups() in the same way. ListField::getOptions() is protected in Joomla 6.2 (the Manual’s examples declare it public, which also works because PHP allows widening visibility). ListField also has addOption($text, $attributes = []) for options added at run time.

Because the options are plain objects, validate="options" on the field checks that the posted value is one of them; always add it for fields whose options are limited by security, such as a "category the user may use".

A field that reads from the database should receive the database from the framework, not from a static factory. FormField implements DatabaseAwareInterface and uses DatabaseAwareTrait, so getDatabase() is available in every field class:

Source: Joomla Manual: Custom fields overview

The Manual’s overview does not document getDatabase() on fields; it comes from DatabaseAwareTrait in the 6.2 source. If a test creates a field by hand, call setDatabase() first.

For a field type that is not a list, extend FormField and implement getInput(). This one shows the number of metres and feet and uses a layout so the markup can be overridden:

Source: Joomla Manual: Example custom fields

The Manual’s Custom2Field follows the same plan with protected $layout = 'custom2field' and a file layouts/custom2field.php that starts with defined('_JEXEC') or die; and extract($displayData);. Its closing reminder is important and easy to forget: include the layouts folder in the extension manifest, or the layout file is not copied by the installer and the field renders nothing (see Extension types, manifests and packaging). Always escape values in a custom getInput(); the base class does not do it for you.

The grid layout and the subform-order-changed event are new in Joomla 6.1; the files are present in the 6.1.0 source tag and absent from 6.0.x. The event is a DOM CustomEvent dispatched by the joomla-field-subform web component after the user reorders a row, and it bubbles up from the subform element. Its detail carries row (the affected row element), fromPosition (the old index) and toPosition (the new index):

Source: Joomla Manual: Subform form field

Load such a script through the Web Asset Manager with a dependency on webcomponent.field-subform. Row positions are renumbered by the component on save, so a listener is for display only.

FormModel::validate($form, $data, $group = null) dispatches onContentBeforeValidateData (with a Model\BeforeValidateDataEvent) so a plugin can adjust the posted data, calls $form->process($data, $group) and returns the filtered array or false. The older event onUserBeforeDataValidation is still dispatched when a listener exists but logs a deprecation and is removed in 7.0, so plugins should switch to onContentBeforeValidateData. After a false result the controller pushes the messages from getErrors() to the user.

The Form class offers a small API to change a loaded form:

Source: Joomla Manual: Manipulating forms

setFieldAttribute() changes the Joomla attribute from the XML, for instance hint; whether that reaches the HTML depends on the field type. To change the value, use setValue(), because bound data overrides the attribute. setFields() adds several. The $replace argument decides what happens when a field with the same name and group exists.

A plugin can add fields to any form whose model dispatches onContentPrepareForm. The system plugin fields that powers custom fields works this way, and so does every core plugin that adds tabs to the article edit screen. In Joomla 6.2 the plugin is a SubscriberInterface listener with the concrete event class (see Plugin development and events):

Source: Joomla Manual: How plugins work

$event->getForm() and $event->getData() are the getters of the event class. The form name is the first argument that the model passed to loadForm(), so a plugin identifies "its" form by comparing it. Forget this check and the plugin runs for every form on the site, including user registration and the login module.