What is stored
Part of Architecture.
One base field on nodes, frame_layout (long text, revisionable, translatable), holds the layout as JSON:
{
"version": 1,
"root": { "props": {} },
"content": [
{
"type": "frame_demo:section",
"version": 1,
"props": {
"id": "section-1",
"heading": "Built on [site:name]",
"variant": "tinted",
"_spacing": { "padding": { "size": "l", "sides": "vertical" } },
"content": [
{ "type": "drupal_field:field_media_image", "props": { "id": "f1", "formatter": { "type": "media_thumbnail", "settings": { "image_style": "large" } }, "label": "hidden" } }
]
}
}
]
}typeis a component id: an SDC (<theme>:<name>), or one ofdrupal_field:<field>,drupal_view:<view>:<display>,drupal_block:<block plugin id>,drupal_paragraph:<paragraph type>(Paragraphs),drupal_saved:<uuid>(a block of the library). A Drupal block has the propstitleand, when its plugin has a settings form,settings(see the table of rendering below).propsholds the values of the component's props, the content of its slots (a list of items under the slot's name) and the values of its features under_spacing,_align,_background,_position.idis unique in the layout. Translations refer to it.root.propsholds what belongs to the page, not to a block:_template, the template the page started from, andhtml, the values the page chose for the attributes of the<html>element that its theme offers ({"data-theme": "dark"}, see html_attributes). A value that is not one of the theme's options is refused by the save and ignored when the page is printed.versionof the document is the layout format (owned by the module,LayoutMigrator::VERSION);versionof an item is the schema version of its component when it was saved.LayoutMigratorbrings both up to date whenever a layout is read, see Versions and migrations.
Because the field is revisionable and translatable, revisions, content moderation and translations cover the layout without anything extra. Which content types use the editor, and how they translate, are third-party settings of the content type (enabled, translation_mode).
Translations
LayoutStorage implements the two modes:
- Synced: the original language holds the layout. A translation's field holds only
{"strings": {"<id>.<prop>": value}}, the translatable props it changed (andversions, the component version those values were saved for). Reading a translation takes the original's tree and puts those values in. Saving a translation walks the original's tree and keeps only values of translatable props that differ, so a request cannot change the structure. - Independent: every translation holds a whole layout. Drupal copies it when the translation is created.
Text, textarea, rich text and link props are translatable; a prop opts out with x-builder-translatable: false.
What a layout uses
With the Entity Usage module installed (tested with 5.0), the module's tracking plugin Frame layout reports what a layout refers to. The page, or the saved block, is the source; the field is frame_layout. Nothing needs configuring, unless the site limits the enabled tracking plugins: enable Frame layout there. For pages that existed before, rebuild the statistics once (drush entity-usage:recreate, or the Batch update tab of its settings).
| What an editor places | What is recorded as used by the page |
|---|---|
| a picked image, an image as a background | the media item |
media embedded in rich text (<drupal-media>) | the media item |
a link picked from the site's content (entity:node/N), a link to a page in rich text | the content |
a saved block, linked (drupal_saved:<uuid>) | the saved block (frame_saved) |
| a copy of a saved block | what the copy holds, as if the editor had placed it; not the saved block |
a block of the Paragraphs Library (drupal_saved:<uuid>) | the item of the library (paragraphs_library_item) |
a Drupal block of a reusable custom block (drupal_block:block_content:<uuid>) | the custom block (block_content) |
a node, term or user named in the settings of a Drupal block as entity:<type>/<id> | that entity |
| a Paragraph block | what its paragraph refers to (media, content, library items, whatever its fields hold) |
a block that follows a preset (_preset) | the preset (frame_preset) |
the template a page started from (root.props._template) | the template (frame_template) |
| a saved block, for the saved block's own layout | the same list: its media, links and custom blocks |
| a preset, for its own values | the same list: its media and links |
| a template, for its own layout | the same list: its media, links, presets and saved blocks |
Not recorded: Drupal blocks that are not reusable custom blocks (menus, branding, views blocks), a placed View, a Field block (the field is the page's own: Entity Usage tracks it as for any page), links typed as a plain path outside rich text, and the paragraphs themselves. Paragraphs are never recorded by Entity Usage: it treats them as inline entities, which have no page of their own, so a paragraph has no Usage tab, and the page is listed as the user of what its paragraphs use, as Entity Usage does for every site with Paragraphs. Which paragraphs a page has is kept in its field frame_paragraphs, and each paragraph has the page as its parent.
A saved block is revisionable, so its records are per revision as a page's are: a draft of a saved block (a revision that is not the default one) is not a use, and publishing it changes what the block uses. A preset or a saved block that is archived is still used where it is linked. Presets, saved blocks and templates are counted by the same service (LibraryUsage), from Entity Usage or from the internal records: a preset is used by the pages, saved blocks and templates that have a block that follows it, once each. A preset that is used cannot be deleted.
Usage is recorded for the revision and the translation of the page that has it:
- A save records what the layout uses; a new revision records it again for that revision.
- An item taken out of the layout is not used by the revisions saved without it. Older revisions keep their use, which the Usage page shows after Include old revisions.
- Deleting a revision, a translation or the page removes its records. Deleting the media, block or content that was used removes the records for it.
- A translation has its own: in the synced mode what it changed (a translated link), in the independent mode its own layout.
Media, content, custom blocks and library items then show the pages that use them on their Usage tab, and Entity Usage's delete warnings apply. The tab is on for the entity types listed in the Local tasks of Entity Usage's settings: the recipe frame_editor_paragraphs sets media, content and library items; add block_content for custom blocks.
LayoutReferences finds the references by walking the stored document, without the components' schemas, so it does not depend on the active theme.
These are covered by EntityUsageTest and EntityUsageParagraphsTest (Kernel: every kind through save, new revision, removal, revision and page deletion, translations).
Export and import
A layout is a field of its page, so it travels with Drupal's content export (core 11.2 and newer):
php core/scripts/drupal content:export node 12 --with-dependencies --dir=../contentand is imported like any exported content: by a recipe that has the files in its content folder, or with core's Importer. Two things are done for it (EventSubscriber\ContentExport):
- In the file the layout is the document itself, under
frame_layout: - layout:, not the JSON text the field stores. It reads and compares like the rest of the file. - What the layout refers to is named by UUID, since ids differ from site to site: the media item of an image (
media_uuid), a link picked from the site's content (entity:node/<uuid>, also inside rich text and lists), the paragraph of a Paragraph block (paragraph_uuid). Each is a dependency of the page, so--with-dependenciesexports it too, and so are the saved blocks the layout links to. On import they get the ids of the importing site; the list of the page's paragraphs is made again from the layout.
Translations are exported with their layout or, in the synced mode, their texts. A link that is typed as a path (/node/12) is left as typed.
The turning of ids into UUIDs and back is one service, frame_editor.portability (LayoutPortability: portable() and local()), used by this subscriber and by the layout file below. The layout file also renames the types of items (fileTypes(), storedTypes()): storage keeps drupal_field:…, a file has field:….
The layout as a file
Core's export is for whole sites and recipes. To move one layout (between pages, between sites, from a script) there is a JSON file with its own format, described in Export and import of a layout:
LayoutExporter::exportNode() ──► { format, layout (UUIDs), translations, includes, references } ──► LayoutImporter::prepare()
LayoutPortability::portable() migrate → check → create → local()
│
LayoutImporter::save() ◄───────────────┘ (new revision, Paragraphs::persist)LayoutExportermakes the file of a page (exportNode(), with the options by reference, a layout of the editor instead of the saved one, a selection of item ids, the unsaved values of paragraphs) or of a saved block (exportSaved()). Blocks of the library and paragraphs the layout names go intoincludes, recursively; media and pages are described underreferences, and with the optionmediathe media items with their files go intoincludes.media(up toexport_media_limitMB, elseExportTooLargeException). The types of items have nodrupal_in a file.LayoutImporter::prepare()checks the file (format, unknown components, components in a newer version: the whole import stops with a list), migrates it withLayoutMigrator, creates the blocks and paragraphs ofincludesthat the site lacks (by UUID: existing ones are used), makes the media items ofincludes.mediathe site lacks (files and media with the UUIDs of the file, when the media type exists and the user may create media), turns UUIDs into ids withLayoutPortability::local(), and asksLayoutValidatorfor warnings. It does not save the page. A paragraph of a page that is not on the site is made from its values the way the editor does for a new Paragraph block: the values wait as the draft of that block (ParagraphDrafts) andParagraphs::persist()makes the paragraph when the page is saved.save()is that save.insert()andinsertItems()do the same for items that are added to a layout that has some (new ids): items in, items out, nothing stored; the paste of components is to use them.LayoutSchemasmakeslayout.jsonandcomponents.jsonfrom the same editor description of the components (ComponentCatalog::ownFields()) and the design tokens (ComponentFeatures,ThemeKit) as the editor and the AI assistant use.LayoutFileControllerhas the routes; the forms insrc/Form/Layout*Form.phpare the tabs.- The format has a version of its own,
LayoutExporter::FORMAT_VERSION. Changing a key's meaning raises it; a new kind underincludesdoes not.