The editor
How the editor is put together in the browser, and how it talks to Drupal. Part of Architecture.
/node/N/edit (admin theme: toolbar, navigation, breadcrumb)
└── iframe /node/N/frame-editor/frame (the editor's own CSS and JS only, no theme assets)
├── Puck: rail │ canvas │ right column
│ └── iframe #preview-frame the canvas: the default theme's CSS and JS, all component libraries
├── iframe /node/N/frame-editor/content?part=fields node form: Content, field group and Menu panels (admin theme)
├── iframe /node/N/frame-editor/content?part=page node form: page settings (admin theme)
├── iframe /frame-editor/media-library Drupal's media library, in a dialog (admin theme)
└── iframe /node/N/frame-editor/preview the page with unsaved changes, in a dialogThe edit route is not changed. BuilderEntityFormController decorates the core service controller.entity_form, which serves every route with _entity_form, and answers with the editor for an existing page of a content type that uses it, when the form is edit (or default); the route has already checked that the user may edit it. Everything else goes to the core controller unchanged, so a module that gives the edit route its own form (_entity_form: node.custom) or controller keeps it. The setting of the content type alone decides: there is no hook to turn the editor off for one page. The add page works the same way: node/add/{type} is the editor for a content type that uses it, for a user who may create that content.
A new page
There is no node on the add page, but the node form works as on the edit page: its frames show the form of a new, unsaved node, and nothing is stored until the first save.
node/add/{type}holds the editor in a frame (/frame-editor/add/{type}/frame). The settings havenode: null,new(the content type) and only the endpoints that need no page. The Content, field group and Page settings frames are/frame-editor/add/{type}/content?part=..., the node form of a new node (the title is in the Page settings; thenode:idtoken is empty). Components can be added; nothing is autosaved.- Save in the editor submits the Page settings form first. Its first save makes the draft: unpublished (the first state of the workflow,
draft, with content moderation), the author is the current user, the language is the one the add form starts with. Without a title nothing is made and the form says so. The two frames share asessionin their addresses, so the Content form saved after the Page settings goes on the same page and does not make a second one; before it, it is refused. - The editor then gets the settings for the new node (
GET /frame-editor/node/N/settings) and puts them over its own in one place (adopt()ineditor/src/newPage.js: every part readssettings.endpoints.*when it needs them), the frames load the forms of the node, and the address of the window around it becomes/node/N/editwithhistory.replaceState. The editor is not reloaded. With no components yet, that save only makes the page; with some, the layout is saved as usual.
Required fields other than the title are not asked for: a draft may be incomplete. Drupal's validation applies when the layout is saved or published, as on the edit page (the editor lists what is missing, and the Content panel has the fields). Leaving the add page before the first save leaves nothing behind.
Why frames. The preview must look and behave as on the site, so the canvas is a frame with the assets of the default theme and every component's library. Drupal's forms must look and behave as in the admin UI, so they run in pages of the admin theme. The editor's own UI has neither: the page of the editor is served by the default theme but without its assets (barePage() without the page attachments). A frame per theme keeps their CSS apart: the media queries and vw units of a design system see the width of the breakpoint chosen, not the editor window; position: fixed elements sit against the canvas; the CSS of a kit does not reach the editor's panels, and the admin theme's does not reach the components.
The canvas
The canvas is Puck's preview iframe (iframe: { enabled: true, syncHostStyles: false }). Puck does not copy the editor's styles into it; the iframe override (CanvasFrame.jsx) fills it from drupalSettings.frameEditor.canvas, which BuilderController::canvas() builds from what the page of a visitor would have: the libraries the modules and the theme attach to every page (hook_page_attachments, so the theme's libraries), the library of every component, core/drupal, core/drupalSettings and core/once, and the editor's frame_editor/canvas (css/canvas.css: the outlines, placeholders and slot rules of the canvas, the only CSS of the editor that is in the frame). The frame gets the drupal-settings-json element (the settings those libraries bring), the inline design tokens of the theme, the style sheets, and the scripts one after the other; the page is shown when they are loaded. What a Drupal block or a view needs beyond that comes with the answer of the render endpoint (assets) and is added to the frame, not to the editor.
The editor's code runs in the editor's window and draws into the frame through portals, so a bare document, window or getComputedStyle is the editor's. Anything that reads or writes the canvas goes through canvas.js (canvasDocument(), onCanvas() for listeners, setCanvasCss() for style sheets of the canvas, canvasItem(id)) or element.ownerDocument.defaultView: the pins and responsive styles of components, the selection outline, the marks of other editors, the keys (Ctrl or Cmd + C, X, V, Z, Y listen in both documents; Ctrl or Cmd + I is Puck's, which watches the frame too), scroll into view, the measuring of hollow components and wrapper: contents slots. Behaviors are attached with the frame's own Drupal and drupalSettings.
The width of the frame is Puck's viewport: the breakpoint tabs over the canvas set ui.viewports.current to the width of the breakpoint (or 100%), and Puck scales a frame wider than the column down to it. A script that listens to DOMContentLoaded itself does not hear it in the frame (the document was ready before the scripts were added): use a behavior, or frame-editor:rendered.
Components are not React components in the editor. For each item the editor posts its type and props to /frame-editor/render and shows the HTML that comes back. Before the old markup of a component is replaced or removed the editor calls Drupal.detachBehaviors() on it, and after the new markup is in place Drupal.attachBehaviors(), so React islands mount as on the site and scripts that keep instances let them go. It then dispatches the bubbling frame-editor:rendered event on the root element of the component for scripts that do not use behaviors, see Scripts of a design system.
Slots need care, because the content of a slot is edited by Puck, not rendered by Drupal:
- Drupal renders the component with an empty marker in each slot:
<div data-frame-editor-slot="content"></div>. - The editor mounts Puck's drop zone into that marker with a React portal.
So inside the editor a slot looks like …slot container > [data-frame-editor-slot] > [data-puck-dropzone] > items. Components that lay their slot out as grid or flex account for that in their CSS, see Layouts. A component with a slot is not mounted as a React island in the editor, because mounting replaces its children.
A slot that says what it accepts gets Puck's allow on its field: the editor lists the components that match (by id, or by the provides the catalog sends with each component, editor/src/accepts.js) and Puck does not drop any other into it. The rules are checked again by Drupal when a layout is saved (LayoutValidator::notAccepted(), rules in SlotRules), because a layout also comes from a file, a paste or an assistant.
The canvas has two modes, switched by two icon buttons (a pencil, a pointing hand) at the right end of the bar of widths above the canvas (or with Ctrl or Cmd + I). In Edit Puck puts an overlay over every component, so a click selects it and nothing inside it can be used. In Interact, Puck's interactive preview, clicks reach the components as on the page: accordions open, tabs switch, modals and React islands work, and nothing is selected. Details that are open in Edit so that their content can be edited are left as the component draws them. The root of the canvas has the class frame-editor-canvas, and is-interacting in Interact mode, so a theme can show what its components hide until a script opens it:
/* In Edit every tab panel is shown, so its content can be selected; Interact is as the page. */
.frame-editor-canvas:not(.is-interacting) .tabs__panel[hidden] { display: block; }A component whose rendered box is empty or too small to click (under 2 px high, and not a thin line between margins) gets a placeholder after it, .frame-editor-hollow with the component's name, in Edit mode. It sits next to the component, not in it, so the component's markup is not changed. The editor measures again whenever the box changes.
Two details that are easy to trip over:
- Type names. Puck addresses drop zones as
<item id>:<slot>and derives the id of a new item from its type. Drupal's ids contain colons, so inside Puck types use/(frame_demo/card);editor/src/types.jsconverts when the layout is loaded and saved. - Position. A component that is placed or pinned gets its position on Puck's wrapper of it, through a small style sheet, not on the component itself. The wrapper is the box its parent lays out, and it is what Puck selects and drags.
The node form
BuilderContentForm extends NodeForm and reports itself as the edit form, so everything modules add to node forms is there. It is shown twice, as two parts:
| Part | Where | Contains |
|---|---|---|
fields | left: Content, Menu and one panel per field group | the fields of the content type; the menu settings |
page | right, with nothing selected | title, state, and the sidebar of the edit page: URL alias, authoring, promotion, revision log, translation, whatever modules add |
A form-level #process callback decides for every element which part it belongs to (the "advanced" group of the edit page is the page part) and removes the elements of the other part, so they are neither validated nor saved by this form.
The panels on the left are one form: every element carries data-frame-editor-section with the name of its panel, and the frame hides the others. With the Field Group module, BuilderContentForm::groupSections() turns the top-level groups of the form display into panels (the tabs of a top-level Tabs group; a Details sidebar group goes to the page part). The same #process callback runs before Field Group builds its groups and rewrites $form['#fieldgroups']: a group that is a panel becomes a plain container with the mark of the panel, groups of the other part are dropped. BuilderContentForm::sections() gives the editor the list of panels without building the form.
The two parts are separate forms that can be changed at the same time. save() therefore does not save the node it was built with: it takes the latest revision, puts only its own fields on it, and saves that.
Unsaved changes
Nothing is written to the node until Publish or Draft. Two per-user stores (Drupal's private tempstore, which expires by itself) hold what is unsaved:
- the layout, posted by the editor a moment after each change (
…/draft); - the field values of the node form. A script in the frame presses a hidden "Keep as draft" button in the background after each change (and after each Drupal Ajax update, which is how media and multi-value widgets change the form).
FieldDraftskeeps the values; validation errors are dropped for that button, so a half-filled form still previews.
Both are used by the render endpoint and the preview page (the draft values are put on a copy of the node), and both are restored when the editor is opened again.
Saving
Publish / Draft
1. each changed part of the node form is submitted (Drupal validates; an error stops here)
2. POST …/save { data, publish | draft }
- text formats: a format the user may not use is accepted only for text that already had it
- new revision from the latest values of every language (storage->createRevision)
- LayoutStorage::store(); state set for Publish / Draft; node validated and saved
- the drafts are deletedA save can therefore make up to three revisions (fields, page settings, layout). Drupal's "modified by another user" check is not applied to the layout save: it compares every translation with the published revision and misfires when another language was saved in between. Several people on one page are kept in step by live editing.
Endpoints
The editor has no permission of its own. Those under /node/N/ need the editor enabled for the content type and update access to the node; the add page needs create access. The rest (_frame_editor_access, BuilderAccess) are open to who may create or edit content of a type that uses the editor, manage the library or the templates, or change the displays of an entity type. POST requests carry Drupal's X-CSRF-Token header.
| Path | Purpose |
|---|---|
GET /node/N/edit, /node/add/TYPE | the editor page (admin theme): the edit and add pages of a content type that uses the editor; other types keep core's form |
GET /node/N/frame-editor/frame | the editor (default theme) |
GET /frame-editor/add/TYPE/frame | the editor of the add page, without a node (default theme) |
GET /frame-editor/add/TYPE/content | the node form of a new page (a part of it), for the frames of the add page; the first save makes the draft |
GET /frame-editor/node/N/settings | the settings of the editor for a page, for the add page to switch to it |
POST /frame-editor/render | HTML of one component, for the canvas |
POST /frame-editor/node/N/save | save the layout; publish or draft set the state |
POST /frame-editor/node/N/draft | keep or discard the unsaved layout |
GET, POST /frame-editor/node/N/presence | who else has the page open, and the latest revision; POST tells where this editor is |
GET, POST /frame-editor/node/N/live | the relay of the live editing: since=N gives the updates after N, POST adds some |
GET /node/N/frame-editor/preview | the page with the unsaved layout and field values |
GET, POST /node/N/frame-editor/content?part=fields|page | the node form |
GET, POST /frame-editor/formatter-form | formatter settings, as an HTMX fragment |
GET, POST /frame-editor/formatter | the same in a frame, where core has no HTMX |
GET /frame-editor/media-library | Drupal's media library |
GET, POST /frame-editor/library | the library of saved blocks: read, save, update, delete |
GET, POST /frame-editor/preset | presets: where one is used, save, update, delete |
GET, POST /frame-editor/template | templates: the items to start from (a copy), usage, save, archive, delete |
GET /admin/structure/frame/display/{display id} | the editor on a display of Manage display (POST /frame-editor/display/{id}/save and /draft for it; the layout is kept in the third party settings frame_editor of the display) |
GET /admin/content/frame/templates/{id}/edit and /admin/content/frame/library/{id}/edit | the editor on a template or a saved block: the edit-form link of the entity, served by BuilderEntityFormController (the entity form is at …/{id}/settings); (POST /frame-editor/template/{id}/save and /draft for it) |
GET, POST /node/N/frame-editor/paragraph | the form of the paragraph of a Paragraph block |
POST /frame-editor/node/N/ai | one turn of the AI assistant (module frame_editor_ai) |
GET /frame-editor/urls, /media, /tokens | link autocomplete, image search without Media Library, token tree |
The editor's sources
modules/frame_editor/editor/src/:
| File | What |
|---|---|
main.jsx | the Puck configuration, the canvas (ServerComponent), header actions, save and drafts |
fields.jsx, featureFields.jsx | the fields of the right column |
BlocksPanel.jsx, fuzzy.js, icons.jsx | the list of blocks, its search and icons |
library.js | the saved blocks the editor knows, and conversion of their items |
presets.js, PresetBox.jsx | the presets the editor knows and the rules of following one; the Preset box and the notes under the options |
templates.js, TemplateBox.jsx | the templates the editor knows; Start from a template, Save as template, the settings of a template and of a display |
AiPanel.jsx | the chat of the AI assistant |
contentFrame.jsx | the frames of the node form |
History.jsx, history.js, liveHistory.js | the history timeline: Puck's steps on templates, the activity of everyone on pages |
TokenInput.jsx, TokenBrowser.jsx, tokens.js, ckeditorTokens.js | tokens: suggestions while typing [, the list of tokens of the T button, the clear button of text fields |
types.js | conversion of component ids |
frameTokens.js | token autocomplete for rich text fields of the node form (a bundle of its own) |
npm run builder:build builds them into js/editor.js, js/editor.css and js/frame-tokens.js. Unit tests of the pure parts (types, tokens, fuzzy, history) run with the base theme's npm test.