Who this is for. Content modellers building a layout's areas, and developers who will read them. After this page you can fill in every field of a layout area knowing what the author will see, and choose names you will not have to change.
The fields
| Field (admin label) | What it does | More |
|---|---|---|
| Name | The identity: what templates ask for and API writes address. Unique within the layout; leading and trailing spaces are trimmed. | Below |
| Type | The input type, which decides the editor and the stored value. | Category and editor |
| Label, Help, Info | What the author reads on the form. | Below |
| Required; # Min. components, # Max. components | Checks made when the record is saved. | Validation and default content |
| Default | The value used while the area is empty. | Same page |
| Supported layouts | For component and collection areas: which component layouts an author may add. | Components and collections |
| Attribute, Attribute attachment | Move the area out of the main form, alone or attached to another area. | Attributes |
| Group and position | Where the field sits on the form. | Below, Area groups |
| Index in search, Index field | Put the value into the site's search index. | Below |
| Hide / show | Retire the area from the form without deleting its content. | What a change does |
The name is the identity
The name is what every template calls, what every API write names, and what a layout switch matches on. Content is stored in the record's revisions, linked to the area itself, so a rename keeps the content but disconnects every template and integration that used the old name: after renaming intro, getAreaText('intro') prints nothing, and {$page->intro} raises "Property intro does not exist" in Smarty and prints nothing in Twig. Choose names as carefully as database columns:
- lower camel case, no spaces or hyphens:
heading,introText,heroImage,pageSections; - named for what the value is, not where it appears or how it is edited:
ctaUrl, notrightButtonLinkortext2; - a switch named for the non-default behaviour,
hideDaterather thanshowDate, because an unset switch and an off switch read the same; - the same name for the same thing on every layout, so templates and components can be shared and a layout switch carries content across;
- never the name of a method the record already has, such as
name,urlorparent: the shorthand would return the method's value instead of the area.
The full convention, with the list of names to avoid, is on Naming conventions and the site audit.
Label, help and info
- Label names the field on the form. Without one the author sees the area name with its first letter in capitals, so
heroImageappears as "HeroImage". - Help says what to enter: "One sentence, under 20 words."
- Info carries the longer explanation: where the value appears, what happens if it is left empty, who to ask.
Help and info both appear as small icons beside the label, each showing its text when the author hovers over it. Fill in help wherever the right entry is not obvious from the label; most sites fill only the label, and it shows in their content.
Position and order
Position sets the order of fields on the editing form, within the area's group (or among the ungrouped areas). It has nothing to do with the order in which the template prints things. In the admin you set it by dragging, and the form numbers the areas 1, 2, 3 for you. Numbering matters when layouts are written through the API: two areas of the same group cannot share a position ("A layout area already exists at this position (3)"), so a script that numbers areas 10, 20, 30 can insert one later without renumbering the rest.
Marking an area for search
An area's value reaches the site search only if the area is marked: switch on Index in search and choose the Index field of the search index it goes into. It is off unless switched on, area by area. Only text areas can be indexed, with any text editor except colour, and the index field must be of the matching kind (a date area needs a date field, a switch a boolean field); the form refuses a mismatch with "You need to use "date" field type for this area" or similar. Saving a layout whose indexing changed starts a reindex of the search index in the background. What the index holds and how a search page reads the field is in How indexing works.