Input types, layouts, components and images
The platform's central abstraction, in one line: an input type defines what an editor can enter, a layout area binds one input type to a named slot, a layout groups areas and points at a template, a record or component holds the content for each area, and the template reads it back. Read this book straight after the template languages.
Reading an area as a property, such as {$component->heading}, is the house style for printing it. It is not sugar for a getter: it tries a real getter first, then resolves the name by the area's category and editor. The order, and what each type returns.
Who this is for. Developers writing or reviewing page and component templates. After this page you can predict what {$component->heading} returns for any area, and keep the tables below open instead of guessing.
A template reads an area either as a property of the record or component, the shorthand, or through a getter that names it:
{* the shorthand: the house style for printing a value *}
<h2>{$component->heading}</h2>
{* a getter: for arguments, attributes and calculations *}
<h2>{$component->getAreaHtml('heading')}</h2>{# the shorthand: the house style for printing a value #}
<h2>{{ component.heading }}</h2>
{# a getter: for arguments, attributes and calculations #}
<h2>{{ component.getAreaHtml('heading') }}</h2>For a plain text area the two lines print the same thing, because the shorthand on text goes through getAreaHtml(). For other areas the shorthand returns something else: a real boolean, a date object, an image. Lead with the shorthand whenever you print a value with no arguments. Use a getter when you need an argument or a method on the result, when an area's name is taken by a getter of the model, or when you need plain text for an attribute, a script or JSON.
On a versioned record, such as a page, a post, a book page, a custom entity record or a global component, both forms read the active revision: {$page->getAreaText('intro')} is {$page->getActiveRevision()->getAreaText('intro')}, and {$page->intro} is the shortest way to the same content. Where that content is stored is on Where content is stored, and what a change does to it.
When a template reads heading as a property, the response model behind the record or component runs these steps, in order:
getHeading(), its result is returned. No area is consulted.Property heading does not exist in, followed by its class name.The sequence is identical in both engines. Twig's attribute lookup reaches the same property and method handling as Smarty's ->, so steps 1 and 2 behave alike. The engines differ only in what the reader sees at step 3: Smarty fails the page, Twig prints nothing. That difference, and the other limits, are on Limits of the shorthand, and the rule.
| Area category | The shorthand returns | The same as |
|---|---|---|
| image | The image object; on the frontend a blank image when the area is empty | getAreaImage() |
| file | The file object, or null | getAreaFile() |
| record | The linked record, or null | getAreaRecord() |
| records | A collection of the linked records, or null | getAreaRecords() |
| text | Depends on the editor, in the next table | |
| component, collection and the rest | The rendered block, as HTML | getAreaHtml() |
Images have a unit of their own, starting at Images in templates. Files, records and blocks in practice are on Files, records and component areas.
| Text editor | The shorthand returns |
|---|---|
switch | A real boolean: true when the stored text is 1, otherwise false |
date, datetime | A printable date object, which prints in the site's date format and takes date methods such as format(); null when empty |
| Every other editor (text, textarea, rich text, select, number, code and the rest) | The stored text, through getAreaHtml() |
These three exceptions are the ones to memorise. A switch and a date never carry the live-preview wrapper, because they are a boolean and a date object rather than text, so they are safe to test and compare through the shorthand:
{* switch: a real boolean *}
{if $component->hideDate}...{/if}
{* date: an object, or null; printed as it is, it uses the site's date format *}
{if $component->eventDate}
<p class="date">{$component->eventDate}</p>
{/if}{# switch: a real boolean #}
{% if component.hideDate %}...{% endif %}
{# date: an object, or null; printed as it is, it uses the site's date format #}
{% if component.eventDate %}
<p class="date">{{ component.eventDate }}</p>
{% endif %}Every other text value is HTML from getAreaHtml(), and in the admin's live preview that HTML is wrapped in an editable marker. What that gives you, and what it costs inside attributes, is on The shorthand and live preview. How each input type is stored and printed is on Text, select and switch areas in templates and the two pages after it.
Step 1 comes first, so an area called name, id, url, slug or fullPath returns the model's own value, not the author's content, and raises no error. Name areas for what they hold, such as heading or ctaUrl. More on a real getter wins.
Was this page helpful?
Your answer goes to the docs team.