Presets
A preset is one look for the blocks of a kind, saved under a name: spacing, colours, width and settings, without the content. Blocks that follow it look the same, and each page keeps its own content.
When to use it
- One look for all blocks of a kind: every "Heading" of a landing page is big, dark and centred, and each page has its own text.
- Options only some people may change: lock the colours and spacing, and leave the text to the editors.
- Only when you need it: you do not need presets to build pages. Use the library to reuse content.
What it does
A preset is a named set of values for the options of one component: a "Big title" for the Heading, a "Dark card", a "Hero with two buttons". Blocks that follow a preset have its values, and a change to the preset changes them all. A preset can lock options: a block that follows it cannot change those.
A preset is not the library, and not a template (a whole page that new pages start from, as a copy). A saved block is one block with everything in it, shown the same everywhere. A preset is only values: each block that follows it has its own content, and may change any option the preset does not lock.
Limitations
- Presets are not translated.
- A component has one default preset. Blocks made by the AI assistant or by an import do not use it.
- Starting content is copied, never linked: a change of the preset does not reach blocks that already have it.
- Paragraph blocks are left out of starting content: a paragraph belongs to one page.
- Overriding a locked option needs Override locked preset options, which is given to nobody by default.
- Slots of a block are not resolved from the preset: they are the block's own.
In the editor
Every component has a Preset box in the right column, under the form of the component and above the Library box. Under its title a short help text says what a preset is and when to use it, as the description of a Drupal form element. The presets of a component are also in the Blocks panel, in a group that folds under the component: a component that has presets, theme presets or variants shows a small arrow button on its row (Show presets / Hide presets, a real button, aria-expanded). Opened, the entries are listed under the row, indented with a guide line, as Site look preset, Sale tag theme, Ghostvariant: first the presets of the site, then those of the theme (Presets a theme ships), then the component's variants. The component and each entry are dragged in like any block, and a click on the arrow neither drags nor adds anything. The groups are closed at first; what you opened is remembered for the session and in the browser (per component). A search that matches an entry opens its component with only what matches (and the component row), and clearing it brings back the groups as you left them. A component without any is listed as before.
| You have | You can |
|---|---|
| a block that follows no preset | Apply a preset (a list of the presets of the component). Save as preset (needs the permission to manage presets): a name, a description, the options to lock, whether what is inside it is kept as the starting content, whether the preset is the default of its component |
| a block that follows a preset | Reset to preset: every option gets the preset's value again. Detach: the block keeps what it shows and follows nothing. Update preset from this block: the preset becomes what this block shows, on every page that uses it (the editor says on how many pages, and names them, first). The box says Used on 12 pages and whether the preset is active or archived. With the permission to manage presets: Archive or Restore, and Delete when nothing uses the preset |
Under every option of a block that follows a preset is a note, so it is clear where the value comes from:
| Note | Meaning |
|---|---|
| lock, Locked by the preset | the preset decides it; the field cannot be changed |
| chain, From the preset | the block has the preset's value |
| dot, Changed on this block (and Reset to preset) | the block has a value of its own |
| open lock, unlocked on this block (and Lock again) | a locked option that this block changes anyway (see below) |
Spacing, size, alignment, text, background, border and position are options like the others: each is one option, with all its values per breakpoint, so locking Background locks the background at every width.
The default preset of a component is what the editor starts the component with when it is added to a page. A component has one default: making another preset the default takes it away from the first. Blocks made by the AI assistant or by an import do not use it.
Starting content
A preset of a component with slots (a Stack, a Card, a section built by the AI assistant) can keep what is in the slots as its starting content. When the preset is applied to a block, or the preset is dragged in, the starting content is copied into the block's empty slots, with new ids. It is never linked: it belongs to the block from then on, and changing it there does not change the preset or other blocks. Update the preset from a block to change the starting content for the blocks added later. Blocks that follow the preset already are not changed.
Paragraph blocks in the starting content are left out: a paragraph belongs to one page.
Locked options and who may override them
| Permission | Allows |
|---|---|
| Edit a page that uses the editor | Apply presets, reset, see where they are used |
| Manage Frame presets | Save as preset, update, rename, archive, restore, delete (when unused), the list in the admin |
| Override locked preset options | Unlock a locked option for one block (Unlock for this block) and give it a value there |
Override locked preset options is given to nobody (it is marked restrict access).
Detach is not offered to a user who may not override when the preset locks something: it would take the lock away.
What a block shows
In a layout a block that follows a preset has "_preset": "<uuid of the preset>" in its props, and only the values that are its own. What it shows is worked out the same way when the page is rendered, in the canvas of the editor and in the editor itself:
| Option | The block shows |
|---|---|
| locked by the preset | the preset's value, whatever the block has. Unless the block lists it in _unlocked and has a value of its own: then the block's |
| not locked, and the block has a value | the block's (it overrides) |
| not locked, and the block has no value | the preset's |
| the preset has nothing for it | the block's |
| a slot | the block's: slots are not resolved |
{ "type": "frame:heading", "version": 1,
"props": { "id": "h1", "_preset": "0b6f…-uuid", "text": "Our summer sale", "_unlocked": ["level"], "level": "h2" } }The editor holds the block with all its values, so the fields and the canvas work as without presets. When the layout is read (fromDrupal) the preset's values are put in; when it is saved they are taken out again (toDrupalLayout). A value equal to the preset's is not stored: the block follows the preset. presets.js has the rules and the tests that go with them (__tests__/presets.test.js).
On the server ItemResolver (the service frame_editor.item_resolver) applies the rules. LayoutRenderer calls it for every item, so a page, a saved block, a preview and the canvas of the editor (POST /frame-editor/render) show the same. The cache tags of the presets used are added to what is rendered, so changing a preset shows at once. The validator, the save check and the AI sanitizer look at an item with its preset's values, so a required option the preset has is not missing. A preset that is gone, or is of another component than the block, is ignored: the block shows its own values.
ItemResolver::guard() is the shared recursion guard: anything else that makes an item out of something that may contain it again works through it, and the same list of what is being built stops a loop.
What is stored when the user may not override
When a layout is stored (LayoutStorage::store(), so the editor's save, an import, a restore) Presets::enforce() applies the permission. A user who may not override locked options cannot add to _unlocked or change the value of an option in it; any other value of a locked option is dropped, as the preset decides it. What was unlocked before by someone who may stays as it was. The AI assistant is held to the same: it cannot set what a preset locks.
Archived presets
A preset is archived instead of deleted: the preset is not offered for new blocks (not in the Blocks panel, not in Apply a preset, never the default), and the blocks that follow it keep working with its values. Restore it to offer it again. This is the same as the Active and Archived states of a template.
A preset can be deleted only when nothing uses it: no page, saved block or template has a block that follows it, in any language. A preset that is used cannot be deleted, in the editor, in the list or by the endpoint: the answer is the pages that use it (the form lists them), and Archive is offered. Archived presets are still counted as used by the blocks that follow them. A preset that was never used, or whose last block is gone, can be deleted.
Presets a theme ships
A theme can ship presets of its own components, in component.yml, so that a look of a design system ("Alert, warning", "Hero with two buttons") is there on every site that uses the theme without anyone making it:
# button.component.yml
thirdPartySettings:
frame_editor:
presets:
big_ghost:
label: Big ghost
description: A large button with an outline.
values: { variant: ghost, size: l }
locked: [size]| Key | |
|---|---|
the machine name (big_ghost) | lower case letters, digits, _ and -; it is what a layout stores, so keep it |
label | the name in the Blocks panel and the Preset box |
description | optional |
values | the options the preset sets, by name: the props of the component, variant for the variants of core, and the features (_spacing, _background...). Not slots: a theme preset has no starting content |
locked | optional: options of values that a block cannot change, as with a preset of the site |
They are listed next to the presets of the site, read-only: in the Blocks panel, in the group under the component (Big ghost, tagged theme), and in the Preset box (Big ghost (theme)), where a block can follow one like any other. The rules of what a block shows, locked options, _unlocked and who may override are the same as for a preset of the site. There is no default among them and nothing to update or delete: the Preset box says From the theme (read-only), and offers Copy to a preset to edit, which makes a preset of the site with the same values and locks (for a user who may manage presets), which the block then follows.
A block stores "_preset": "theme:big_ghost", and only the values that are its own. The reference is the machine name, read with the component of the block, so it does not depend on the theme that provides it: another theme that has a component with the same id and a preset of that name gives the same. A reference that is not there (the theme was changed, the preset removed) is ignored: the block shows its own values. An export names it as it is stored (nothing is included in the file) and an import keeps it when this site has it, else drops it with a warning. Nothing about it is counted as Used on: it is not an entity.
A preset with a mistake is left out as a whole: a name that is not a machine name, no label, values that are not a map, a name that is not a prop (or is a slot) of the component, a value the schema of the component refuses. The locked names that are not in values are dropped. The AI assistant is told them with the presets of the site.
Finding presets, and where they are used
All presets are listed under Content → Frame → Presets (/admin/content/frame/presets): the name, the component, the locked options, whether it is the default, the Status (Active or Archived), Used on (the number of places that use it), when it changed, with Edit (name, description, default), Used (a tab next to Edit at /admin/content/frame/presets/{id}/used: a link to every page, saved block or template that uses it, its type, and "This preset is not used anywhere." when there is none), Archive or Restore, and Delete, 50 to a page. A filter above the list narrows it by status and by component (?status=active|archived, ?component=). The list is the same kind of list as the library's and the templates'.
Where a preset is used is counted like the library: with Entity Usage when that module is installed (the page, saved block or template is listed as using its presets, on the preset's Usage page; a preset uses the media and links in its own values), else from the module's own entity frame_usage. What is counted is each page, saved block, template or preset that has a block that follows the preset, once however many blocks do, from the default revision and every translation. The counts are kept up to date when any of them is saved or deleted, and the cached counts are invalidated by their cache tags. The library of saved blocks is counted the same way. Display layouts are not counted.
Export and import
A file of a layout includes the presets its blocks follow, once each, in includes.presets; a block names its preset as "_preset": "frame_preset:<uuid>". See Export and import. On import a preset the site has (by UUID) is used, a missing one is made for a user who may manage presets, and otherwise the block gets the preset's values and follows nothing.
Component versions
Presets are migrated with the content when a component changes (Versions and migrations): the values and the starting content go through the steps like any item, and the names of the locked options follow the renames and removals. A post update function (ContentMigrator::batch()) stores it for presets with the rest, and a preset is migrated when it is read until then. Blocks that follow a preset are migrated as before, so a renamed option stays where it was.
How it is stored
A preset is a content entity, frame_preset (class Preset): a name, a description, component (copied from the layout on save, for the list and the filter), state (active or archived), locked (a JSON list of prop names), is_default, a log of saves (the last 50: who, when, the message) and, in the field frame_layout, a layout document with one item: the component, its version and its props, with the features and their per breakpoint values (at). A prop that is a slot holds the starting content. Presets (the service frame_editor.presets) reads and writes them.
Presets are not translated, as saved blocks are not: a block that follows one has the same values in every language, except what the block has of its own. (frame_editor_update_11008).
For the AI assistant
The assistant is told the presets of every component (name, description, locked options, and the values when they are few) and may give an item "_preset": "<uuid>"; it then gives only the options that should differ. What the preset locks is dropped from what it proposes. See AI assistant.