Paragraphs
What it does
With the Paragraphs module, every paragraph type is a block of the builder. Use it for content that is better edited as fields in a Drupal form than as props of a component: structured content with its own field types, widgets, validation and templates.
Nothing needs enabling: with Paragraphs (and Entity Reference Revisions, which it requires) installed, the Blocks panel has a Paragraphs group with one block per paragraph type.
Limitations
- Nested paragraphs are listed in Structure but are edited only in the form of the Paragraph block; the editor sees one block, and nesting is followed five levels deep.
- A Paragraph block whose form was never filled in is empty: the editor shows a placeholder, the page nothing.
- Undo and the history of the editor do not take back what was typed in the form; use the undo of the field you are in. Discarding the unsaved changes of the page drops it all.
- Duplicating a Paragraph block gives a second block that names the same paragraph until one of them is changed and the page saved.
- The form is shown in the page's language. Tokens are not replaced in paragraph fields.
In the editor
Drag a paragraph type onto the page and select it. The right column shows the paragraph's own form: its form display, with every widget (rich text, media, references…), and under it the layout options every block has (spacing, alignment, background, position).
The form has no button. What you type is kept in the background, per user, and the canvas shows the paragraph with it a moment later. The paragraph itself is created, or changed, when you Publish or save a Draft, together with the rest of the page. Until then it is an unsaved change like any other: a reload brings it back, Preview shows it, and discarding the unsaved changes drops it.
The paragraph is rendered by Drupal with its default view display and your theme's paragraph templates.
What is stored
The content is in the paragraph, not in the layout. The layout says which paragraph, in which revision, and holds the layout options:
{ "type": "drupal_paragraph:text_block", "version": 1,
"props": { "id": "…", "paragraph": { "id": 12, "vid": 57, "uuid": "6d9b…" }, "_spacing": { "padding": { "size": "m" } } } }- Saving the page saves the paragraph. A paragraph that was changed in its form gets a new revision (a new block: a new paragraph) when the page is saved, and the layout names that revision (
vid). The values are validated then; an invalid value stops the save with its message. Older revisions of the page keep showing the paragraph as it was. - Unsaved values are kept by
ParagraphDrafts(Drupal's private tempstore), by page, language and block. Only the editor and its preview show them. - The paragraphs belong to the page. The page lists them in an Entity Reference Revisions field,
frame_paragraphs, filled from the layout on every save, and each paragraph has the page as its parent. That is the relation Paragraphs expects: the paragraphs are deleted with the page and are not seen as orphans. The field is added to nodes when the modules are present (also when they are installed later; existing sites:drush updb). - Translations. A translation names its own revision. In the synced mode the structure is shared and the paragraph reference is one of the things a translation may change, so a translator edits the form in their language and gets their own revision. When the paragraph type is translatable (Content Translation), that revision holds the translation of the paragraph; otherwise it is simply another revision with the translated text.
- Entity Usage never records paragraphs themselves, as a source or as a target: they are inline entities with no page of their own. The page is listed as using what its paragraphs use (media, content, items of the Paragraphs Library), for every revision and translation of the page; a paragraph taken out of the layout stops counting for the revisions saved without it. A page that shows an item of the Paragraphs Library is listed on that item's Usage tab. See what a layout uses.
Reusing a paragraph
Save the Paragraph block to the library: the Library box is under the form of the paragraph, above Layout and style. Pages that use the saved paragraph show it as it is saved now; updating it, with a revision log message, updates them all.
With the Paragraphs Library module the library is that module's: Save to library makes an item of Content → Paragraphs, which is also usable in paragraph fields of other content types, and has revisions with their log messages. A page that uses it gets a paragraph of the type From library that names the item. The editor makes that paragraph when the page is saved and drops it when you choose Edit copy here; it is not a block to add by hand, so it is not in the Blocks panel. Items made in Content → Paragraphs are in the Library group of the Blocks panel like the ones saved in the editor. Saving and updating need the module's permissions Create and Edit paragraph library item, deleting Administer Paragraphs library.
Published or hidden. Pages show the default revision of an item, and only while the item is published. The module has no archived state, so an item that is not published is hidden: pages that use it show nothing in its place, as when it is deleted (also for users who administer the library), and the Library box says Unpublished. The Library box tells the status (Unpublished, Draft pending) and Update on a copy publishes the item, shown on every page that uses it. To hide an item (unpublish) or show it again, or to publish a draft, use Content → Paragraphs: the box has no buttons for that. With Content Moderation managing the item, a draft is a revision that is not the default one: pages keep showing the published revision, and hiding needs a state called archived in the workflow of the item. Content Moderation is not needed.
Without the module a saved paragraph is a saved block of the editor's own, with a paragraph that belongs to it. The recipe frame_editor_paragraphs installs it, with Entity Usage and a starter paragraph type.
Drawn by a component
A Paragraph block is drawn by the default view display of its paragraph type. With UI Patterns a layout on that display, a component with the fields mapped to its props and slots, draws the block instead of the fields of the paragraph: the same component can then also be placed in the editor directly. The status report warns when such a mapping no longer fits its component.
A paragraph type from a component
With Paragraphs and UI Patterns the page of the components can make a paragraph type from a component: a field for each prop and a view display that draws the paragraph through the component. Props without a matching field type are skipped and listed. Each slot becomes a field of nested paragraphs, put in the slot by the view display. See UI Patterns.
Nested paragraphs
A paragraph can hold other paragraphs, in fields of the type Entity reference revisions that point to paragraphs (the widget Paragraphs). They are edited in the form of the Paragraph block, as always.
Structure shows them under the block, grouped by field. When the view display of the paragraph type uses the layout of a component and puts the field in one of its slots, the group has the name of the slot. Each nested paragraph shows its type and a short summary, and so do the paragraphs inside it, a few levels deep.
They are read-only there: they cannot be dragged, removed or saved on their own. A click on one selects the Paragraph block and goes to its field in the form. What Structure lists is what the canvas shows, so values typed in the form and not saved yet are in it.
From a paragraphs field
A site that already built its pages with an Entity Reference Revisions field of paragraphs can move them into the editor with a one-time Drush command:
drush frame:from-paragraphs node.landing.field_paragraphs # dry run
drush frame:from-paragraphs node.landing.field_paragraphs --executeThe argument is <entity type>.<bundle>.<field>. The content type must use the editor, and the field must be a paragraphs field. Every paragraph of the field becomes a Paragraph block at the top of the layout, in the same order.
- Without
--executenothing is saved. The command lists, for each page, how many paragraphs would become blocks, of which types, and what is skipped. --ids=1,2limits the conversion to those pages.- A page that already has a layout is skipped;
--overwritereplaces the layout. - A paragraph whose type the editor does not offer, or that is gone, is skipped and reported.
- The blocks name copies of the paragraphs (nested paragraphs included), which belong to the page's editor paragraphs. The old field and its paragraphs are not changed or deleted: remove the field yourself once you are sure.
- A page gets a new revision with the log message "Converted from field_x by frame:from-paragraphs". In independent translation mode every translation gets its own layout from its own field values; in synced mode the translations share the layout of the original, and the paragraph translations come with the copies.
Run it on a copy of the database first: it is meant to be run once.