Skip to content

Library of saved blocks ​

The library is where blocks are kept to be used again: a component saved with everything in it, a saved block, that any page can use. Pages that use it show it as it is saved, and one change updates all of them.

When to use it ​

  • Content that must read the same on every page: a call to action, a contact strip, a notice. Change it once and every page that uses it changes.
  • A block that editors reuse as it is, such as a paragraph of the Paragraphs Library.
  • Not for sharing only a look with different content: use a preset.

What it does ​

Any component can be saved to the library and used on other pages: a call to action, a contact strip, a section with a heading, text and buttons, a notice that must read the same everywhere. Change it once, and every page that uses it changes.

If only the options of a component should be shared, not its content, use a preset. To start pages from a whole page, copied, use a template; a saved block placed in a template stays linked on the pages that start from it.

Limitations ​

  • Saved blocks are not translated: a linked block shows the same text in every language (tokens and Field blocks follow the page). Where text must differ per language, use a copy.
  • A saved block is one component. To save several, put them into a layout component first (the Structure panel does it for you).
  • What is inside a linked block cannot be selected on the page: make a copy to change it.
  • Field blocks in a saved block show the field of the page it is placed on; in the editor of the saved block they show an example or a placeholder.
  • Deleting a saved block that is used leaves nothing in its place on the pages that link to it; copies stay. Archiving it does the same, and can be undone.
  • Saving, publishing, archiving and deleting need the permission Manage the Frame library.
  • Pages show the published block only. A draft cannot be previewed on a page yet: only in the editor of the saved block, which opens from the draft.
  • The editor of a saved block has no copy and paste yet.

In the editor ​

Every component has a Library box in the right column, under its form and the Preset box and above Layout and style. It is a collapsible like the ones of Drupal's forms (a details element with the title Library in its summary), closed until you press the summary (the whole title row is the toggle, there is no Show or Hide button); opened, it starts with a short help text, in the look of the description of a Drupal form element, that says what the library is and when to use it; it stays as you left it while you work, also when you select another component. Closed, a saved block or a copy of one shows its name next to the title. Like the box of Drupal's node form that says Published, it tells what the component is, whether it is used from the library or is a copy, the name of the saved block, when it was last saved and by whom, and the last revision log message.

You haveYou can
any component (a Paragraph block, a component of the theme with others in its slots, a Field block, a view...)Save to library as…: give it a name, and a revision log message if you like. It is saved with everything in it, and here it becomes a saved block
several components selected in the Structure panelSave to library… (the bookmark button next to "+"): they are put into a Layout component first, which is saved. Here the saved block takes their place, in one step of Undo
a saved block (it is in the Library group of the Blocks panel, drag it in like any block)Edit copy here: use a copy of the saved block here and change it, the library keeps its version. The box also tells the status and a draft that waits; to publish or discard a draft, archive, restore or delete the block, use the library list
a copy of a saved blockUpdate: what is here becomes the published saved block, on every page. Reset to saved block: drop the changes and show the saved block again

The two ways a page can use a saved block:

  • Linked. The page has the saved block, not its content. It shows the block as it is saved now: update the saved block and every page that links to it changes, without being saved again. On the canvas a linked block is one item; what is in it cannot be selected.
  • A copy. Made with Edit copy here. The items are the page's own: it no longer follows the saved block. The first item remembers where it came from, and its Library box says it is a copy.

So to change a saved block: Edit copy here where you see it, change it, Update. The copy becomes a link again. Revision log message, above the buttons, is where you say what you changed; it is kept with the revision (who, when, the message) and shown in the box wherever the block is used.

States: published, draft pending, archived ​

A saved block has revisions. Pages show the published revision only, which is the default revision of the block.

StateWhat pages showWhat the editor and the lists say
Publishedthe published revisionPublished; offered in the Blocks panel
Draft pending (a published or archived block that also has a draft)the published revision, as before; the draft changes nothingDraft pending, with the date and the author of the draft; Publish draft and Discard draft
Archivednothing in its place, as when a block is deleted, but it can be restoredArchived; not offered in the Blocks panel; blocks that are already on pages stay where they are, empty
  • Publish (Update on a copy, and what Save in the editor of a saved block does): the new content becomes the published revision on every page that links to it. A draft that was waiting is replaced by it.
  • Draft: a new revision that is not the default one, made through the library endpoint (the editor of a saved block, or an API client). There is one draft at a time: a new draft replaces the old one. The editor of the saved block opens from the draft, so work can go on until it is published. Publish draft makes it the published revision; Discard draft deletes it and the published block stays as it is.
  • Archive: the block stays in the library with its content, the pages that link to it show nothing, and it is not offered for new use. A draft that waits stays. Restore shows it again. A block that is archived is still counted as used where pages link to it.

These operations are in the list of the library, not in the box: Publish draft, Discard draft, Archive and Restore, each with a confirmation that names the pages. The list has a Status column and a filter by status (Published, Draft pending, Archived) next to the filter by component.

Draft revisions are not counted as use: only what the published revision links to is. Content Moderation is not needed and not used for a saved block; the states are the default revision and the published flag of the entity.

The editor of a saved block ​

A saved block can also be changed on its own page, without a page that uses it: Edit in the list of the library, the edit address of the block (/admin/content/frame/library/{id}/edit; the editor replaces the form that was there, and the old /frame-editor address is gone; the Library box of a component has no link to it: it overrides, updates or saves a draft, and publishes the draft, discards it, archives or restores the block). The editor opens with the one item of the block, and works as on a page: the Blocks panel, the forms, Undo, and a draft that is kept for you until you save or discard it.

  • Save asks for the name of the block and a revision log message, and publishes: every page that links to the block shows the new version at once. When a draft waits, the editor opens with the draft; saving publishes it with your changes.
  • A saved block is one component. To save several, select them in the Structure panel and put them into a layout component with "+" first; a save with more than one item at the top is refused.
  • It needs Manage the Frame library and access to update the saved block.

Spacing, alignment, background and position of a linked block are set where it is placed, per page; what is inside is the same everywhere.

Two things are shown for what is in a saved block:

  • Paragraph blocks in it are the saved block's own paragraphs. Saving gives it paragraphs with what was typed in the forms, even when the page was never saved.
  • Field blocks show the field of the page the saved block is placed on, not of the page it was saved from. The box says so when the block has one. In the editor of the saved block there is no page: a Field block shows its Example (text, or an image, set in its form), or without one a placeholder with the label of the field. The example is only for the editor canvas: pages never show it, and the cards and the list of the library do not either.

Finding saved blocks, and where they are used ​

Saved blocks are in the Library group of the Blocks panel, and its search finds them by name and by the component they are made of. Under the name of each block is the component it is made of and where it is used: Stack · on 12 pages, or not used yet. The numbers come from Entity Usage when that module is installed; without it the editor keeps its own small records (the internal entity type frame_usage), with the blocks each page and saved block links to (the published page, every language). A block is counted once per page, however often it is placed there; copies do not count.

All saved blocks are listed under Content → Frame → Library (/admin/content/frame/library): the name, the component, how many blocks are in it, Used on (the number of places), when it changed, with Edit (the editor), Settings (the entity form: the name), Used (a tab next to Edit, /admin/content/frame/library/{id}/used, with a link to every place that uses it), Export and Delete, 50 to a page. The list can be narrowed to one component (each saved block stores its component in a field of its own, component, so filtering and paging are database queries). New blocks are made in the editor. With Entity Usage, the counts of the whole library are asked of its usage service, one block after the other, and kept in the cache until a page, saved block, preset, template or item of the Paragraphs Library changes.

Deleting a saved block that is used asks first and lists the pages, here and in the editor. Deleting does not touch copies. Pages that link to it show nothing in its place, and the editor says so. To keep the block and only stop showing it, archive it.

Who may do what ​

PermissionAllows
Edit a page that uses the editorPlace saved blocks, make a copy of one, see where one is used
Manage the Frame librarySave to the library, publish, save a draft, archive, restore, rename, delete, the editor of a saved block, the list in the admin, export of a saved block

Items of the Paragraphs Library keep the permissions of that module.

How it is stored ​

A saved block is a content entity, frame_saved (class SavedBlock): a name and, in the same field and format as the layout of a page, a document with one item. It is revisionable and has a published flag (status); the revision log message, user and time are those of the entity's revisions. Library (the service frame_editor.library) reads and writes them: publish() saves a new default revision, saveDraft() a new revision that is not the default one, archive() unpublishes the block (or publishes it again), and pending() finds the draft. Loading a block gives the default revision, so everything that renders a block shows the published one.

In a layout:

json
{ "type": "drupal_saved:0b6f…-uuid", "version": 1, "props": { "id": "…", "_spacing": { "margin": { "size": "l" } } } }
json
{ "type": "my_theme:section", "version": 2,
  "props": { "id": "…", "heading": "…", "content": [ … ], "_library": { "uuid": "0b6f…", "label": "Promo", "overridden": true } } }

The first is a link, the second a copy.

  • A saved block is rendered by LayoutRenderer like the rest of the page, in the context of the page it is on: tokens such as [node:title] and Field blocks in it show that page's values.
  • Its cache tag is on every page that links to it, so an update is visible at once. An archived block returns nothing but its cache tag, so pages show it again when it is restored.
  • Versions and migrations apply to saved blocks as to pages.
  • Paragraphs in a saved block are the saved block's own. Saving or updating gives it its own paragraph, with what was typed in the form even when the page was never saved; an update is a new revision of it. A copy on a page gets a paragraph of its own when the page is saved. So a page and the library never write to the same paragraph.
  • With the Paragraphs Library module, a paragraph saved from the editor is an item of that library, not a frame_saved entity; a layout links to it the same way, drupal_saved:<uuid of the item>, and also names the page's From library paragraph. See Reusing a paragraph. The states differ there: that module has no archived state (see below).
  • A saved block may contain other saved blocks; one that would contain itself is shown once.
  • With Entity Usage, pages are listed as using the saved blocks they link to (not the ones they have a copy of), and a saved block as using its media, links and custom blocks. An item of the Paragraphs Library is listed as used by the pages that show it, on its Usage tab.

Saved blocks are not translated: a linked block shows the same text in every language (tokens and Field blocks follow the page). Where text must differ per language, use a copy.