Skip to content

Rendering a page ​

Part of Architecture.

node view (full) ──► hook_node_view_alter ──► LayoutStorage::load() ──► LayoutRenderer::build()
                                                                              │
                 one render array per item:  #type => component, #props, #slots (children, recursively)

EntityHooks::nodeViewAlter() runs for the full view mode of content types that use the editor. When the page has a layout, it replaces everything else in the build with it. Other view modes are untouched.

For every item LayoutRenderer first asks ItemResolver for what the item shows: an item that follows a preset gets the preset's values (and the cache tags of the preset). Then it makes a core #type => component element. On the way it:

ValueWhat happens
text propstokens replaced ([node:title]), in the language of the page
link propsentity:node/N becomes the URL of that page in the page's language; dangerous protocols are stripped
rich text propstokens replaced, then filtered by the stored text format (check_markup)
image propsresolved by MediaItems: URL of the image style, and <picture> / srcset / alt for the props the component names
length propsa step of the theme's scale or a custom length, as a CSS length
featuresCSS declarations, put on the root element through the attributes prop
drupal_field:*$node->get($field)->view() with the chosen formatter and its settings
drupal_view:*a #type => view element, only for displays of the type Component
drupal_block:*the block plugin's build(), in the theme's block markup, after its access check. The prop settings is the plugin's configuration; a block that needs the page gets it as its entity:node context

Drupal blocks ​

A Drupal block has two props. title is its label (translated, tokens allowed). settings is an object with the configuration of the block plugin, and it is in the layout only when the plugin has a form beyond the standard fields (label, display of the label, provider, context mapping). The editor shows the plugin's own form below the title, as on the block layout page: inline with HTMX (Drupal 11.2 and later), applied at every change, or in a dialog with an Apply button without it. Both are the form BlockSettingsForm (routes frame_editor.block_settings and frame_editor.block_settings_form), and it needs no page, so a template and a saved block have it too. The values go through validateConfigurationForm() and submitConfigurationForm() of the plugin, so blockValidate() and blockSubmit() run; what is stored is getConfiguration() without id, label, label_display, provider and context_mapping. A change that does not validate is not applied, and the editor says so. Nothing is saved in Drupal: the settings are part of the layout. They are not translated (only title is), and the AI assistant neither sees nor changes them: a kept block keeps its settings, a new one starts with the defaults.

A block with a required context is offered when the page can give it: a context of entity:node (the entity being edited, with the content type checked where the context asks for one). A block that needs anything else (a user, a language, a string) is not offered. On the page, in the editor and in the preview the block gets the entity being rendered, in the editor with the values typed in the form and not saved yet. Where there is no page (the editor of a template or of a saved block) it shows its name in a placeholder, as a Field block does, and prints nothing on a page that has no entity. The cache tags of the page entity are added to the block.

Cache metadata of everything used (tokens, URLs, media, image styles, blocks) bubbles to the page, so the result is cached like any other render array.

What is checked on the way out ​

The layout is data typed by editors, so nothing in it is printed as is:

  • Text is escaped by Twig; rich text goes through its text format.
  • Links: javascript: and other dangerous protocols are removed.
  • Lengths are a token of the theme or match number + unit; colours are a name of the theme's palette; alignment and position are one of a fixed list. Anything else is dropped.
  • Image URLs in CSS are escaped for url("").
  • A view is rendered only if its display is of the type Component and the user may see it; a block only after its own access check.