Joomla Custom Fields

Contexts are open. Any component whose extension class implements FieldsServiceInterface (or FieldsFormServiceInterface) appears in the context drop-down of the Fields screen. The section on making a component field-aware shows the code. Tags are a special case: the context for items shown in a tag view is taken from the item’s own type alias, so a trail tagged family-friendly renders the same fields in a tag list as in its own list.

The category assignment is evaluated when the form loads. When an author changes the category of a new article the form reloads and shows the fields of the new category, which is why a page that "loses" typed text on a category change is behaving as designed. A field with no assigned category appears for every category. The Tallpine site assigns distance-km, elevation-gain and gpx-file to the category Trails, so they show for Trails → Alpine and Trails → Valley and are hidden for News.

The Options tab is split into three panels. The settings are stored in the params column of the field.

Form Options

Display Options

Smart Search

Publishing shows the creation and modification data of the field, and Permissions has the ACL for the individual field (see below).

Number and Integer differ in storage and in input. Integer offers a list of whole numbers generated from a first value, a last value and a step, and the selected value is stored as a number; because a select list always has a selection, an Integer field always renders. Number is a real number input that accepts decimals, can be left empty and can show currency formatting. For the Tallpine trail, distance-km is a Number field with step 0.1 and the suffix km, whereas elevation-gain is an Integer field with First 0, Last 3000 and Step 50.

Older books such as Joomla! 4 Masterclass (2023) describe the field types of Joomla 4 and have no Number or Note type; they suggest a Text or Integer field with a filter for decimal data. Since Joomla 6.0, use Number.

Note (added in 6.0) is a layout element rather than a data field. It stores nothing: it prints a heading and a text into the edit form and, when Display in Frontend is on, into the output. Use it to put instructions between fields, for example a hint above the trail data: "Enter the distance as measured by the GPX track". The settings are:

Because a Note holds no data, there is no default value to set. Several Notes can be used to give a long form some structure; they are ordered like any other field.

The Media field stores a reference to a file chosen in the Media Manager. Up to Joomla 6.0 it was an image picker, and the edit form offered the options Directory, Preview and Image class. The output was an img element built with the layout joomla.html.image; the stored value is a JSON object that carries the image file and its alt text, and older plain-string values are converted on the fly.

Joomla 6.1 extended the plugin with three more types, announced as the "Three New Media Custom Field Options: Audio, Video & Documents". When you create a field, the type list now contains Media, Audio, Document and Video, which are the layouts media, media_audio, media_document and media_video of the same plugin. Each type restricts the Media Manager modal to files of the matching kind, taken from the Media Manager options for image, audio, video and document extensions.

Two practical consequences follow. First, the files a field can choose from are exactly the extensions allowed in the Media Manager options (image_extensions, audio_extensions, video_extensions and doc_extensions), and an upload is rejected when the extension is not in restrict_uploads_extensions or the MIME type is not in upload_mime (while Check MIME is on). The Tallpine gpx-file field is a Document field, and a GPX track is not in the default list, so the club’s administrator adds gpx as a document extension and application/gpx+xml as an allowed MIME type before authors can attach tracks. Second, the files come from the Media Manager, so the access of an author to upload follows the Media Manager’s Create permission: an author without it can choose existing files but cannot upload.

Because the 6.1 types are layouts of the plugin, a site that upgrades from 6.0 keeps its existing image fields unchanged. The 6.1 series also fixed the behaviour of the form when the type of a Media field is switched and the form reloads. See Media Manager for the options.

A Subform field groups other fields into a repeatable list. Create the member fields first, set Only Use In Subform to Yes on each, and then add the Subform field: select Repeat (more than one row), an optional Maximum Rows, and add the member fields one by one, with Render Values deciding whether the member is printed. The form layout can be the default, a repeatable form, a grid or a table (the Form Layout setting on the Subform field). Rows are stored as JSON in the single value of the Subform field and are printed as ul.fields-container with one li per row.

Two pitfalls are documented by the User Guide and the changelog. A Calendar field inside a subform can raise a fatal error when the article is saved a second time unless Show Time is set to Yes for it. And duplicate subform fields are removed on save, with a warning in the 5.4 and later series. The Tallpine site uses a subform called waypoints, with a Text field waypoint-name and a Number field waypoint-altitude, to list the passes of a multi-day route.

The system plugin listens to onContentPrepareForm. For a supported form it calls FieldsHelper::prepareForm(), which loads the fields of the context and of the item’s category and fires onCustomFieldsPrepareDom once per field. The type plugin returns a DOM node that becomes a normal Joomla form field in the form group com_fields. The media plugin, for instance, changes the type of the node to accessiblemedia and disables the field for a user who may not upload.

When the item is saved, the plugin handles onContentAfterSave:

For a user, the same flow is run from onUserAfterSave, with the exception of the tasks activate, block and unblock, because those would otherwise wipe the stored data. When the item is deleted, onContentAfterDelete removes its values.

FieldsHelper::getFields($context, $item, $prepareValue) is the central API. It reads the published fields of the context, filters them by the category of the item and, on a multilingual site, by the item’s language, and returns copies of the field objects with these properties:

With $prepareValue, getFields() fires three events around the preparation: onCustomFieldsBeforePrepareField, onCustomFieldsPrepareField (the type plugin renders) and onCustomFieldsAfterPrepareField. A plugin can change the field before preparation or the HTML afterwards. Since Joomla 5.3 these events are concrete classes in Joomla\CMS\Event\CustomFields and field plugins are SubscriberInterface subscribers; code that still reads the generic Event::getArgument() array, as shown in older books such as Developing Extensions for Joomla! 5 (2023), should use getField(), getItem() and getContext() on the event objects.

The system plugin also handles onContentPrepare: it fills $item->jcfields, an array of prepared fields keyed by field ID. The Web Services API uses the same helper and exposes every field as an attribute named after the field.

Inside an article text, two tags insert fields. The Content - Fields plugin replaces {field 12} by the field with ID 12 and {fieldgroup 3} by every field of group 3. The tag can be followed by a layout name, for example {field 12 trail-badge}. The editor button Fields inserts the tag from a list. Tags are a convenience for editors; a template author who needs stable markup should rather use overrides, because IDs change between environments.

Set Automatic Display to Do not automatically display, then print the fields where you want them in the view override. The array $this->item->jcfields is keyed by field ID, so build a lookup by name first.

Source: Joomla User Guide: Template overrides for custom fields

Two details matter. The value property is already prepared by the type plugin (plain-text types such as Text and List are encoded, an Editor field is HTML), so print it without further escaping; the rawvalue property is the stored text and must be escaped by the override with htmlspecialchars() or a safer helper. And jcfields only contains fields that passed the category, language and access checks, so test with isset() instead of assuming every field exists. The User Guide example for contacts uses the same idea in html/com_contact/contact/default.php, and the same code works for users and articles.

FieldsHelper::render() first looks for a layout with the requested name in the layout folders of the component of the context, and falls back to the layout of com_fields. In a template the search order for field.render includes:

The Tallpine template replaces the wrapper for every field, to print the label as a dt style heading and the value in a badge, by adding a file to the child template.

Source: Joomla source: components/com_fields/layouts/field/render.php

The list wrapper is fields/render.php in the same folders. Overriding it changes the ul.fields-container markup for all the fields of a position, for example to print them as a Bootstrap definition list.

The Layout option on the Options tab lists the layouts that exist in the component’s layouts/field folder and in html/layouts/{component}/field, html/layouts/com_fields/field and html/layouts/field of every enabled site template. Files named render.php and files starting with an underscore are not offered. When you pick a layout, the list wrapper calls field.{layout} instead of field.render for that field only. The Tallpine difficulty field uses a layout trail-badge:

Source: Joomla source: the Layout option of a field

The raw value is reduced to lower-case letters before it becomes part of a class name, so a changed option list cannot inject markup.

The tmpl/{type}.php file of a field plugin can be overridden like a module or a view, in html/plg_fields_{type}/{type}.php. Use this when every field of one type should print differently, for example every Url field. The core Url type prints the generic text "Visit website" for external links. The Tallpine site wants a labelled link with an icon and a visually hidden warning that the link opens a new window:

Source: Joomla source: plugins/fields/url/tmpl/url.php

The plugin file receives the variables $field, $fieldParams (the plugin parameters merged with the field’s own parameters, where the field wins) and $context. The same technique draws a colour swatch for a Color field, which the User Guide describes, or an audio element with a download link for the Audio type. Prefer an override of the plugin file to editing the plugin, which an update replaces.

The form layout of some types is selectable in the field options (Form Layout on List, SQL, Radio, Integer and Subform), for example a fancy select with search for a long list. The input markup of other types comes from the standard form field layouts under layouts/joomla/form/field, which a template can override in html/layouts/joomla/form/field. See Forms and form fields.

The Content web services plugin registers CRUD routes for the field definitions (v1/fields/content/articles and v1/fields/content/categories) and for the groups (v1/fields/groups/content/articles and v1/fields/groups/content/categories). For the values, an article in the API carries every field as a top-level attribute named after the field, and a write moves those attributes into the com_fields array before saving. The headless Tallpine trail map reads a trail like this:

Source: Joomla source: the articles API controller

The user behind the token must hold Edit Value for the fields, as in the administrator. Joomla 6.2 enables the API token plugin and disables the Basic Auth API plugin on a fresh installation, so use tokens.