Skip to content

Extend Display Builder with buildable plugins

A buildable plugin connects the builder to one kind of display: where its sources are stored, who may build it, where its builder lives and how a draft is published. Display Builder ships five: entity_view, entity_view_override, page_layout, view_display and pattern_preset.

The builder never reads or writes the display itself. It works on an Instance entity, the draft with its history, and asks the buildable plugin to move sources between the instance and the permanent storage. See Internals for the storage of each shipped plugin.

Attribute

Plugins live in src/Plugin/display_builder/Buildable/ and implement DisplayBuildableInterface.

#[DisplayBuildable(
  id: 'page_layout',
  label: new TranslatableMarkup('Page layout'),
  instance_prefix: 'page_layout__',
)]
final class PageLayout extends ConfigBuildablePluginBase {
  • id: plugin ID
  • label: name of this kind of display
  • instance_prefix: prefix of the instance IDs, read with getPrefix()
  • description: optional, one sentence shown where displays of several kinds are listed

Configuration

The configuration is what the Instance entity stores, in its buildable field, to build the plugin again: an entity ID, a display ID. Keep it small and serializable. A constructor may accept a loaded object, such as the page layout PageLayout takes as entity, and keep only its ID in the configuration.

An instance ID is opaque outside the plugin that composes it: read the plugin off the Instance entity, never parse the ID.

Base classes

Extend one of them rather than implementing the interface from scratch.

DisplayBuildablePluginBase implements the profile form, the profile permissions, instance creation, preview of a draft and translation URLs. A plugin extending it implements:

  • getInstanceId(): NULL while the display does not exist yet
  • getSources() and publish(): read the published sources, write the instance sources back
  • getProfile() and getBuilderUrl(): the base returns NULL and the front page
  • access(): answers for the display, with the operation asked on its instance, see Security model
  • getRuntimeContexts(): the contexts the source plugins may use
  • getTranslationLanguages(): the languages the display is translated or translatable to

ConfigBuildablePluginBase is for a display stored in a config entity. It implements getSources(), publish() and getTranslationLanguages(): publishing writes the default language to the config entity and every other language to a language config override, created on the fly. A plugin extending it implements three more methods:

  • getConfigName(): the full config name, used to address the language overrides
  • getSourcesConfigKey(): where the sources sit in that config
  • saveDefaultSources(): writes the sources to the override-free config entity

getInitialSources() and getInitializationMessage() set the sources and the history message of a new instance.

Listings

The admin instances list reads instance storage, so create the instance when Display Builder is enabled on a display, with initInstanceIfMissing(), and a display enabled by a config import is listed too.

The Instances panel lists the plugin's displays only once it overrides collectDisplays(), which returns none in the base class. It is answered by a plugin built with no configuration, and must be read-only: no initInstanceIfMissing(), no instance loading, nothing saved. An unbounded collection honors the limit option, and collectDisplaysBound() says what it left out. Override toUrl() for the collection and add-form links of the group heading.

Overrides

A display overriding another, as entity_view_override overrides entity_view, implements DisplayBuildableOverrideInterface: getOverridden() gives the plugin of the overridden display, getDefaultSources() its sources, and deleteOverride() empties the stored override at once, outside the instance history.

See also