Guide 05 · Developer docs

Content types and custom entities

Which built-in type fits which purpose, how categories, tags, slugs, custom URLs and SEO settings behave across them, how revisions and publishing gate what the public sees, how to model a domain the platform has no type for, and where uploaded files live.

L1–L3
Unit 05 · Custom fields

Defining a custom field

Custom fields Page 28 of 35 Updated

A custom field is defined once for an entity: a name, an input type, a label and help, a required switch and default content. What each setting does, the order fields take on the form, and what making a field required does to existing records.

Who this is for. Content modellers and developers adding custom fields in the admin. After this page you can define a field with the input type, validation and default it needs, place it where authors expect it, and change it later without blocking their edits.

The settings of a definition

Custom fields are defined in the admin's Custom Fields screen. A definition holds these settings (the admin's labels in bold):

SettingWhat it does
The nameThe key templates and the API use, such as jobTitle. Unique per entity, not across the account: a person and a product can each have a field called code.
EntityThe kind of record the field is added to, from the sixteen listed on Where custom fields attach.
TypeThe input type, which decides the editor authors get and the shape of the value.
LabelWhat authors see on the form. "If not specified, the custom field name will be used": the admin then shows the name with each word capitalised.
Help, InfoGuidance for authors, shown with the field.
Required"Control whether or not this field is required". See Validation.
DefaultDefault content, entered with the editor of the chosen type. See Defaults.

Required and default belong to the definition, so they are the same for every record of the entity; neither can be set per record.

Choosing the input type

A custom field uses the same input types as layout areas, with the same categories and editors: see Category and editor decide behaviour. Only five categories are allowed: text, image, file, record and records. A custom field is never a component or a collection, and the Type list on the form offers only input types of those five categories.

The text category covers every text editor, so a custom field can be a plain text, a textarea, rich text, code, a colour, a number, a switch, a date or datetime, a select or a multiselect, as well as an image or a file. The Default setting offers the matching editor for each.

Where it appears on the form, and in what order

A record's custom fields are shown together, as one group on the record's admin form, each under its label, or its name with each word capitalised when it has no label.

There is no position setting. A definition has no order of its own, and the form lists an entity's fields in the order the database returns them, which in practice is the order they were created. The Custom Fields screen can sort its table by any column, but that changes the list on that screen, not the form. To control the order authors see, create the fields in that order. A field added later appears after the existing ones.

Validation

A custom field carries two kinds of validation, both from its definition:

  • Required. A record must have a value for the field.
  • The input type's own rules: a select's list of options, a maximum length, a regular expression. They are the rules a layout area of the same type applies; no validation rule is specific to custom fields.

Both are checked when the record that owns the value is saved, as part of that record's validation, not when the field is defined. A record without a value for a required field is refused with the message "Content for the custom field … is required", naming the field.

Making a field required later

Switching Required on for a field that already has records takes effect from each record's next save, not immediately: existing records are checked then, and that save fails until the field has a value, even when the author was changing something unrelated.

Fill the values before you make a field required

On an entity that already has records, give every record a value first, for example through the API (Custom fields in the APIs guide), and switch Required on afterwards. Otherwise the next author to save any of those records is refused.

Defaults: two layers

Two different defaults apply when a record has no value stored, and they are easy to confuse:

  1. The field's default, set in Default on the definition. When a record has no stored value, the getters return this content instead.
  2. The template's default, the second argument of getCustomFieldText() and getCustomFieldBoolean(). It is used only when there is still nothing: no stored value and no field default.

getCustomFieldImage() and getCustomFieldFile() take no second argument; when there is no image or file to return, they return null.

Template code 
{* the field's default applies first; '_self' and false only when there is still nothing *}
{$target = $element->getCustomFieldText('target', '_self')}
{$isMegaMenu = $element->getCustomFieldBoolean('isMegaMenu', false)}
{# the field's default applies first; '_self' and false only when there is still nothing #}
{% set target = element.getCustomFieldText('target', '_self') %}
{% set isMegaMenu = element.getCustomFieldBoolean('isMegaMenu', false) %}

Reading every kind of custom field, and what each getter returns when a value is missing, is on Reading custom fields.

Go deeper
GuideCustom fields or layout areas GuideWhere custom fields attach GuideReading custom fields GuideCategory and editor decide behaviour

Was this page helpful?

Your answer goes to the docs team.