Settings Tray API

Settings Tray API

Overview and terminology

The Settings Tray module allows blocks to be configured in a sidebar form without leaving the page. For example:

• For every block, one can configure whether to display the block title or not, and optionally override it (block configuration).
• For menu blocks, one can configure which menu levels to display (block configuration) but also the menu itself (menu configuration).
• For the site branding block, one can change which branding elements to display (block configuration), but also the site name and slogan (simple configuration).

Block visibility conditions are not included the sidebar form.

The API: the form in the Settings Tray

By default, the Settings Tray shows any block's built-in form in the off-canvas dialog.

However, many blocks would benefit from a tailored form which either:

• limits the form items displayed in the Settings Tray to only items that affect the content of the rendered block
• adds additional form items to edit configuration that is rendered by the block. See \Drupal\settings_tray\Form\SystemBrandingOffCanvasForm which adds site name and slogan configuration.

These can be used to provide a better experience, so that the Settings Tray only displays what the user will expect to change when editing the block.

Each block plugin can specify which form to use in the Settings Tray dialog in its plugin annotation:

forms = {
  "settings_tray" = "\Drupal\some_module\Form\MyBlockOffCanvasForm",
},

In some cases, a block's content is not configurable (for example, the title, main content, and help blocks). Such blocks can opt out of providing a settings_tray form:

forms = {
  "settings_tray" = FALSE,
},

Finally, blocks that do not specify a settings_tray form using the annotation above will automatically have it set to their plugin class. For example, the "Powered by Drupal" block plugin (\Drupal\system\Plugin\Block\SystemPoweredByBlock) automatically gets this added to its annotation:

forms = {
  "settings_tray" = "\Drupal\system\Plugin\Block\SystemPoweredByBlock",
},

Therefore, the entire Settings Tray API is just this annotation: it controls what the Settings Tray does for a given block.

See also

core/misc/dialog/off-canvas.es6.js

settings_tray_block_alter()

\Drupal\Tests\settings_tray\Functional\SettingsTrayBlockTest::testPossibleAnnotations()

File

core/modules/settings_tray/settings_tray.api.php, line 8