Who this is for. Content modellers and developers deciding where a new value should live. After this page you can say whether it belongs in a layout area or a custom field, and why.
Two mechanisms, defined in different places
A layout area is defined on one Layout record in the admin. It exists on a record only while that layout is assigned to the record, and two layouts used by the same kind of record can offer different layout areas. Its content is stored in the record's revisions, so an edit is a new revision and goes live when that revision does.
A custom field is defined for a kind of record (an entity, such as person, menu element or product), not for a layout. Every record of that kind has the same custom fields, whichever layout it uses, or none. Custom field values are not versioned: they belong to the record itself, so a change is live as soon as it is saved.
| Layout area | Custom field | |
|---|---|---|
| Defined on | One Layout record | An entity: every record of that kind |
| Present on a record | While the record uses that layout | Always, whatever the layout |
| Stored | In the record's revisions; a change is a new revision | On the record itself; not versioned, live once saved |
| Input types | Every category, including component and collection | Only the categories text, image, file, record and records |
| Read in a template | The shorthand ({$page->intro}) or a getter | A typed getter such as getCustomFieldText(); there is no shorthand |
| Which records | Records that have a layout | A fixed list of sixteen entities |
The rule
Use a layout area for content an author composes for one record: a heading, a body, an image chosen for this page, a set of components. Use a custom field for a structured attribute that every record of a kind shares and that a template reads wherever the record appears: a menu element's icon, a person's job title, a category's display title.
When that is not enough to decide, ask two questions:
- Should the value travel with a revision? If it should be drafted, published with the rest of the content and kept in the record's history, it is a layout area.
- Can the record take a custom field at all? Only sixteen entities can (the list is on Where custom fields attach). For any other record the choice is made for you.
The short form of the rule, "layout areas for records with a layout, custom fields for records without one", is a good first guess. The real dividing line is that fixed list, not whether a layout exists, and the cases below are where the two differ.
Borderline cases, resolved
A menu element's icon and mega menu flag: custom fields
A menu element has no layout, the values differ from element to element, and the menu template reads them while it loops over the elements. Custom fields on menu elements are how sites usually carry an icon, a CSS class, a link target or a "mega menu" switch.
A "featured" flag on a page: a layout area
It feels like an attribute, but a page (a record of the Pages module) is not one of the entities that accept custom fields, so there is no custom field to reach for. Add a switch layout area to the page's layout. The flag is then stored in the page's revisions and published with its content.
Books, units and book pages: both
The three levels of a book are the only records that carry layout areas and custom fields at once. A book page has a layout like a page, yet unlike a page it accepts custom fields. Put what the reader reads, and anything that should be drafted and published with the content, in layout areas. Put an attribute that every book (or unit, or book page) has whatever its layout, and that may change without a new revision, in a custom field.
Layout records: custom fields only
A Layout record accepts custom fields but has no layout areas of its own: the layout areas it defines are slots for the records that use it, not content on the layout. A custom field on a layout suits a setting about the layout itself.
Custom entity records: their definition does the job
A custom entity record does not accept custom fields. Its custom entity definition already names the fields every record of that type has.
The difference in a template
On a book page, which has both, a layout area is read with the shorthand and a custom field with its getter. Reaching for a custom field with the shorthand fails: