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

Rename or retire a layout area without losing author content

Published

Content is stored against the layout area, not its name, so a rename keeps content and breaks templates; retire by hiding, never deleting; and change a type across categories by adding a new area and moving the content.

Context

Context. A record's content is stored against the layout area by its internal id, while a template asks for it by the layout area's current name. From those two facts: a rename keeps every record's content but breaks every template and integration still using the old name; a hidden area disappears from the form but keeps rendering; a deleted area takes its content with it, with no undo. Plan the change as a small migration.

Steps

  1. To rename: search the repository for the old name in quotes and as a shorthand property; change the layout and every hit; deploy them together. Check integrations that write the layout area through the API.
  2. To retire: hide the layout area. Its content keeps rendering until each record is next saved, and it can be unhidden. Delete only when nothing has read it for a release.
  3. To change the type across categories (text to image): add a new area with the new type, move the content across (an API script, record by record), switch the template to the new area, verify signed out, then hide the old one.
  4. During the transition, read the new area and fall back to the old, so nothing goes blank while records are migrated.

Code

Shell 
# every template that reads the area, by getter or shorthand
grep -rEn "getArea\w*\(['\"]headline['\"]\)|->headline\b|\.headline\b" templates/
Template code 
{* transitional read: the new area first, the old one while records migrate *}
{$heading = $page->getAreaText('heading')}
{if empty($heading) && $page->hasAreaWithName('headline')}{$heading = $page->getAreaText('headline')}{/if}
<h1>{$heading|escape}</h1>
{% set heading = page.getAreaText('heading') %}
{% if heading is empty and page.hasAreaWithName('headline') %}{% set heading = page.getAreaText('headline') %}{% endif %}
<h1>{{ heading|e }}</h1>

Why this and not that

Not delete-and-recreate under the new name: the content is gone the moment you delete. Not changing the type in place across categories: the old content counts as empty and is lost at the next save. Within a category (text to select) an in-place change is fine, and existing values are checked against the new rules on the next save. Deleting a layout area is offered to developers only, for this reason.

Go deeper
GuideThe chain from input type to template GuidePattern: attributes to CSS classes

Was this page helpful?

Your answer goes to the docs team.