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 09 · Patterns, live preview and upkeep
Renaming and retiring without losing content
Patterns, live preview and upkeepPage 44 of 45Updated
The full procedure for renaming a layout area, moving content to a new area or type, and retiring an area or a layout: the order of steps that keeps authors' content, why hiding comes long before deleting, and what cannot be recovered.
Who this is for. The developer and the content modeller carrying out a change to a layout that already has content. After this page you can plan the change step by step and know, before you start, which steps cannot be undone.
The admin labels it “Hide this area (content will not be removed immediately, but when new records / revisions are saved)”. The area leaves the editing form. Templates keep reading the stored value until a record is next saved; the revision saved then does not have it.
“Show this area (revert hiding)” puts it back in the form. A record saved while the area was hidden has the value only in its earlier revisions.
Delete a layout area
The admin warns: “Deleting areas with existing content will irretrievably delete that content too.” Only users of the Developer type are offered the delete button for a saved area.
None.
Hide a layout
The layout leaves the layout and component pickers. Records already on it keep it and still render.
The admin has no action to show it again; clear its hidden date through the API.
Delete a layout
The layout is removed with no check for records that use it. Only users of the Developer type can delete one.
None.
Nothing in the platform refuses a delete because content still depends on it. The order of steps below is the only safety net.
Hide only after nothing reads the area
Hiding is safe for the content but not for the page. If a template still reads a hidden area, the value vanishes from each record the next time that record is saved, one record at a time. Switch the templates first, then hide.
Renaming a layout area
Renaming keeps the content. It is linked to the area by id, so the next read finds it under the new name (Area names are effectively permanent). The risk is every reader of the old name.
Find every reader of the old name: the templates (command below), and every integration that writes the area through the API.
Prepare the template and integration changes that use the new name.
Rename the area in the admin and release the template change at the same time; update the integrations in the same window.
Load the pages on that layout signed out and check that the value shows.
Shell
# every template that still reads the area "intro", by getter or by shorthand
grep -rEl 'getArea\w*\(.intro.\)|->intro\b|\.intro\b' templates/
A match is a lead to check: ->intro on an unrelated object matches too. Run the same search again before any delete; it answers whether every reader has been changed.
Moving content to a new area, or to another type
When the content must move to a new area, for instance because the input type changes category (text to image), a rename is not enough. Migrate in this order:
Create the new area on the layout, with its new input type. Leave the old one in place.
Copy the content across, record by record, writing each value into the new area through the API (Writing areas shows the request) and converting it on the way when the type changes.
Switch the templates to read the new area, and release them.
Verify on the public site, signed out, that every page on the layout shows the content from the new area.
Hide the old area. Authors stop seeing it in the form; the values stay in the revisions already saved.
Delete the old area only after a release has gone by with nothing reading it: run the search for the old name again and check the integrations. Deleting removes the old values from every record for good.
Authors keep editing during a migration. Copy and switch close together, and either ask authors not to edit records on the layout between steps 2 and 3, or copy again the records changed in between.
Retiring a layout
Move the records on it to another layout. When a record changes layout, the admin copies each value into the area of the same name on the new layout; values with no area of the same name are left out of the new revision, and only earlier revisions keep them. Give the new layout the same area names for the content you want to keep.
Replace its components, for a component layout: find where authors placed it, as in the audit for unused layouts, and swap those components for another kind.
Hide the layout. It leaves both pickers; anything still on it keeps rendering.
Delete it in a later release, if at all. A hidden layout no longer appears where authors choose layouts.
What cannot be recovered
The content of a deleted layout area, on every record that had it.
A deleted layout. Nothing checked whether records used it before it went, and records left on it have no layout to return to.
Hiding loses nothing that cannot be found again: a record saved while an area was hidden still has the old value in its earlier revisions, and a hidden layout or area can be shown again.