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.
L1–L3
Unit 06 · Rendering areas in templates
Text, multiselect values and dates
Rendering areas in templatesPage 21 of 45Updated
The shorthand prints a text area's value and getAreaHtml is its explicit form; getAreaText returns what the author stored, for attributes and comparisons; getAreaValues returns a multiselect's keys as an array and getAreaDate a date object. What each returns, the empty case, and the patterns for class lists and dates.
Who this is for. The template developer printing text-category areas. Afterwards you can choose between the stored and the rendered value, read a switch and a multiselect, and format a date without failing when the area is empty.
Stored value or rendered value
getAreaText(name) returns the value as the author stored it, a string, or null when the area is empty. getAreaHtml(name) returns the area rendered for the page, and it works for every category, not only text: a record, records, component or collection area renders the referenced record's or component's template. For a text-category area the two return the same string, except under live preview (below).
To print a value into the page, write the shorthand: {$component->heading} in Smarty, {{ component.heading }} in Twig. On a text area it calls getAreaHtml(), so it is the normal way to print content, and getAreaHtml() is its explicit form. Use getAreaText() where the value is data: an HTML attribute, a class name, a comparison, a script or JSON. There you want the stored string alone, without the live-preview element described below.
getAreaText() on an area outside the text category, an image or a record, does not throw. It returns the string Error: cannot get text content for area of type … followed by the input type's name and category, and that string lands in the page wherever the template prints it. If you see it, the template is calling the wrong getter for the area.
Live preview and the choice of getter
When a page is rendered for live preview, the getters wrap a text area's value in an editable element, <span class="live-preview-container" contenteditable="true" data-path="…">, so the author can edit it in place. The two getters do not wrap the same areas:
getAreaHtml() wraps any text-category area.
getAreaText() wraps only an area with the richtext editor.
So a heading printed with the shorthand or getAreaHtml() is editable in live preview and one printed with getAreaText() is not. A richtext area read with getAreaText() still carries the span, which breaks it inside an HTML attribute. The shorthand and how live preview uses it are in The area shorthand.
Switches
A switch is a text-category area with the switch editor. The shorthand returns a boolean, true when the switch is on, so {if $component->hideImage} ({% if component.hideImage %} in Twig) is the normal test. getAreaText() returns the string '1' when it is on, never a boolean, so compare its result with '1'. A switch that is off and one that was never set read back the same, so name a switch for the behaviour that differs from the default: hideImage, not showImage.
Multiselect values
getAreaValues(name) returns the option keys a multiselect area holds, as an array, even when only one option is selected. The values are the keys stored for the options, not their labels. For any other editor, the single select included, it returns an empty array; it never returns null. Read a select's one key with getAreaText().
The common use is adding the selected keys to a class list:
{% set classes = ['card'] %}
{% set modifiers = component.getAreaValues('modifiers') %}
{% if modifiers is not empty %}
{% set classes = classes|merge(modifiers) %}
{% endif %}
<div class="{{ classes|join(' ') }}">
In Smarty, array_merge() and implode() are PHP functions the template security policy allows; array_map() and sprintf() are not, so build lists this way rather than by mapping over them.
Dates
getAreaDate(name) returns a PHP \DateTime for an area with the date or datetime editor. The stored value is a string, Y-m-d for a date and Y-m-d H:i:s for a datetime, and the getter parses it into a new object on every call. Format the object, not the stored string.
An empty area returns null.
A stored string that does not parse returns null and logs a warning; it does not throw.
A filled area with any other editor throws: "Could not get date from area … as it is not a date / datetime type".
Test for null before formatting:
Template code
{$starts = $page->getAreaDate('eventStart')}
{if $starts}
<time datetime="{$starts->format('c')}">{$starts->format('j F Y')}</time>
{/if}
{% set starts = page.getAreaDate('eventStart') %}
{% if starts %}
<time datetime="{{ starts|date('c') }}">{{ starts|date('j F Y') }}</time>
{% endif %}
Smarty also has a format modifier for dates. {$page->getAreaDate('eventStart')|format} prints the date in the format configured for the site (the Globals.i18n date settings) and prints nothing when the value is empty, so it needs no test. Twig has no equivalent of its own: use Twig's date filter with a format, as above.