To do after:

Problem/Motivation

Child 5 of #3624396: Plan: Harden InstanceInterface, IslandInterface and DisplayBuildableInterface as public API before RC1. Islands are what contrib extends most, so their API has to be right before RC1.

  • An island calls the instance a builder: build(InstanceInterface $builder), buildContent(), getHtmlId(string $builder_id), and the protected $builder and $builderId of IslandPluginBase. The 11 on*() methods of the same island say $instance, as does the rest of the API. The builder is the editing UI, as in getBuilderUrl(). The instance is the entity.
  • keyboardShortcuts() is a static method, called on the class, so an island cannot answer from its configuration. Its docblock promises a map of keys to descriptions.
  • type is optional on #[Island], while an island without a type does not work.
  • afterBuild() is declared twice, on IslandInterface and on IslandWithFormInterface. reloadWithNodeData() has no caller.
  • ThirdPartySettingsInterface has the short name of core's config entity interface, for a single getSummary() method.
  • Docblocks: the on*() methods call $instance an ID, and IslandInterface does not say how to extend it.

Proposed resolution

  • $builder becomes $instance and $builderId becomes $instanceId: the protected properties of IslandPluginBase, and the arguments of build(), buildContent() and getHtmlId(), in every island. Renamed outright before RC1, with a change record, as every API change up to beta9. No contrib island is known, and display_builder_ai and the dev tools change in lockstep, requiring the release that renames.
  • The other protected members contrib uses stay as they are: $nodeId, $data, the promoted services, buildButton() and reloadWithLocalData(). Child 9 lists them as supported.
  • getKeyboardShortcuts(): array on the interface replaces the static keyboardShortcuts(), which is removed. The base default returns no shortcut, the islands that declare one override it, and ProfileViewBuilder calls it. Its docblock gives the shape it really returns.
  • type required on #[Island]. Every island passes named arguments, so moving it after label breaks none of them. Fallback: keep the default, and throw from the plugin manager for an island without a type.
  • afterBuild() leaves IslandWithFormInterface, and stays on IslandInterface. reloadWithNodeData(), which has no caller, is removed.
  • ThirdPartySettingsInterface renamed outright.
  • Docblocks of IslandInterface and the on*() methods. docs/island-plugins.md drops the promise that build() may return NULL.

Remaining tasks

  • Name the replacement of ThirdPartySettingsInterface.
  • Update display_builder_ai and the dev tools, and raise their constraint on drupal/display_builder.
  • Write the change record.

User interface changes

None.

API changes

  • IslandPluginBase::$builder and $builderId renamed to $instance and $instanceId. Arguments renamed in build(), buildContent() and getHtmlId().
  • New IslandInterface::getKeyboardShortcuts(). keyboardShortcuts() removed.
  • type required on #[Island].
  • reloadWithNodeData() removed. ThirdPartySettingsInterface renamed.

Data model changes

None.

Comments

mogtofu33 created an issue. See original summary.

mogtofu33’s picture

Issue summary: View changes
mogtofu33’s picture

Issue summary: View changes
mogtofu33’s picture

Status: Active » Needs work