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 IDlabel: name of this kind of displayinstance_prefix: prefix of the instance IDs, read withgetPrefix()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():NULLwhile the display does not exist yetgetSources()andpublish(): read the published sources, write the instance sources backgetProfile()andgetBuilderUrl(): the base returnsNULLand the front pageaccess(): answers for the display, with the operation asked on its instance, see Security modelgetRuntimeContexts(): the contexts the source plugins may usegetTranslationLanguages(): 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 overridesgetSourcesConfigKey(): where the sources sit in that configsaveDefaultSources(): 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¶
- PHP Architecture - the chain from a buildable to its instance
- Extend with island plugins - the other contract contrib extends
- Translations - how the builder edits each language