How-to library · Developer docs

How-to library

Task-shaped pages: a title that starts with a verb, the situation in a few lines, the steps, the working code in both engines, and why this way rather than another. Found from a search, done, and left.

How-to Layouts, areas and components

Organise a long editing form with area groups

Published

Groups split a form past about ten fields into named, collapsible sections, ordered as you set them; ungrouped areas follow after. Templates are unaffected: they read areas by name whatever group holds them.

Context

Context. A hero layout with a heading, an intro, an image, its alt text, a call to action with a label and a URL, a background style and an anchor id is a wall of fields. Groups turn it into "Content", "Media", "Call to action" and "Advanced", each collapsible, in the order you set. The template does not care: it reads every layout area by name, in or out of a group.

Steps

  1. On the layout, add the groups, named for the author's task ("Hero", "Call to action"), not the page's structure ("Section 1").
  2. Assign each layout area to a group and order the groups; areas left outside any group render after the groups.
  3. Leave attributes out of groups: the platform moves an attribute out of its group when the layout is saved, because attributes have their own tab.
  4. To remove a group, move its layout areas out in the same save, or they are deleted with it.

Template code

Template code 
{* nothing about groups reaches the template: read areas by name as always *}
<h1>{$page->heading}</h1>          {* group: Content *}
{$page->getAreaImage('image')->getResized(1600, 700, 'fit')->getHtml()}  {* group: Media *}
<a class="btn" href="{$page->getAreaText('ctaUrl')}">{$page->ctaLabel}</a>  {* group: Call to action *}
{# nothing about groups reaches the template #}
<h1>{{ page.heading }}</h1>
{{ page.getAreaImage('image').getResized(1600, 700, 'fit').getHtml() }}
<a class="btn" href="{{ page.getAreaText('ctaUrl') }}">{{ page.ctaLabel }}</a>

Why this and not that

Not splitting the layout into several layouts to shorten the form: one record, one layout, and a record cannot spread over two. Not prefixing area names with the group ("heroHeading", "heroImage") to fake grouping: names are permanent and groups are not, and the prefix survives a regrouping as noise. Not more than five or six groups: past that, the group list is itself a wall.

Go deeper
GuideThe fields of a layout area GuidePattern: attributes to CSS classes

Was this page helpful?

Your answer goes to the docs team.