Skip to content

Architecture ​

How Frame is put together: what is stored, how a page is rendered, and how the editor talks to Drupal. Read Frame (editor) first for what it does.

PageAbout
this pagethe idea, and where the code is
What is storedthe layout field, translations, what a layout uses (Entity Usage), export and import
Rendering a pagefrom the layout to render arrays, Drupal blocks, what is checked on the way out
The editorthe frames, the canvas, the node form, unsaved changes, saving, endpoints, sources
Editing togetherpresence, the shared document, the relay, saving and the History with several editors

The idea ​

  • Drupal renders, the editor only edits. A page is a tree of Single Directory Components. The published page is built by Drupal from Twig and loads no editor code. The editor (Puck, a React app) shows the same HTML, which it asks Drupal for, component by component.
  • The theme is the design system. Components, spacing scale, palette, image styles, breakpoints and which features a component has all come from the active theme and its base themes. The module adds no look of its own to the page.
  • Drupal's forms stay Drupal's. Fields of the page, page settings, menu settings, the media library and formatter settings are the real Drupal forms, shown inside the editor. Nothing about them is reimplemented.

Problems of a block ​

A check that knows the block it is about reports { id, type, field, message }: the id of the item in the layout, its component, the setting that is wrong and a sentence. The save endpoints (page, display, template, saved block) put them in problems of their 422 answer, next to the errors sentences, and LayoutValidator::refusals() makes them. The editor (problems.js, Problems.jsx, ProblemList.jsx) marks the block on the canvas and in Structure, lists it with a Go to block button, and keeps Save, Publish and Draft disabled until the block is changed; the server stays the authority and refuses the same. A list whose component is gone is the first such problem: see Fields with many values.

Where things are ​

frame/                         the base theme
├── components/                         layout components: columns, flex, stack, image (Twig + CSS)
└── modules/frame_editor/     the module (Drupal finds it inside the theme folder)
    ├── src/                            namespaces by area (Drupal\frame_editor\…)
    │   ├── Component/                  what the editor can place
    │   │   ├── ThemeKit                design tokens and feature defaults of the active theme
    │   │   ├── ComponentCatalog        the components, and the field of every prop
    │   │   ├── ComponentFeatures       spacing, align, background, position → CSS
    │   │   └── ComponentSchema, SchemaWatcher   versions and changes of component schemas
    │   ├── Layout/                     the layout of a page
    │   │   ├── LayoutStorage           reads and writes the layout of a node, per translation (and of any entity with the field)
    │   │   ├── LayoutMigrator          versions of the layout and of its items; migrations
    │   │   ├── LayoutReferences        media and content a layout refers to (for Entity Usage)
    │   │   ├── LayoutRenderer          layout → render arrays
    │   │   ├── LayoutValidator, LayoutSchemas, ItemResolver   checks, JSON schemas, what an item shows with its preset
    │   │   └── Source/                 where a layout comes from: node, draft, saved block, preset, template, config
    │   ├── Item/                       the items of a field with many values: ItemChains (the chain of views, preloading), ItemProps, unwrapper plugins (Plugin/FrameItemUnwrapper)
    │   ├── Portability/                export and import files (LayoutExporter, LayoutImporter, MediaImporter, LayoutPortability)
    │   ├── Library/                    the library of saved blocks (Library, LibraryUsage; Entity/SavedBlock.php)
    │   ├── Preset/                     presets: values of a component's options, the rules of locking (Entity/Preset.php)
    │   ├── Template/                   layout templates: the copy a page starts with, archive (Entity/Template.php)
    │   ├── Paragraphs/                 paragraph types as blocks (with the Paragraphs module), and their drafts
    │   ├── Media/                      picked images: URL, <picture>, link, background sources; the media library dialog
    │   ├── Content/                    FieldDrafts (unsaved values of the node form, per user), NodeProperties (Publish and Draft), content migration and report
    │   ├── Controller/                 BuilderController (the editor page, render, save, draft), ContentFormController,
    │   │                               MediaController, LookupController, LibraryController, PresetController, TemplateController,
    │   │                               BuilderEntityFormController (makes the editor the edit page; decorates controller.entity_form)
    │   ├── Form/                       BuilderContentForm (the node form inside the editor), FormatterSettingsForm, admin forms
    │   ├── Hook/                       the hooks (#[Hook] classes)
    │   └── Plugin/…                    Views display "Component", Views style "React component (SDC)",
    │                                   field formatter "Responsive image" for media
    ├── modules/frame_editor_ai/   the AI assistant (needs the AI module)
    ├── editor/                         the editor: React sources, built with Vite into js/
    ├── js-static/                      small scripts that run inside the frames
    └── css/