annotate core/modules/settings_tray/settings_tray.api.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 1fec387a4317
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 /**
Chris@0 4 * @file
Chris@0 5 * Documentation for Settings Tray API.
Chris@0 6 */
Chris@0 7
Chris@0 8 /**
Chris@0 9 * @defgroup settings_tray Settings Tray API
Chris@0 10 * @{
Chris@0 11 * Settings Tray API
Chris@0 12 *
Chris@14 13 * @section sec_overview Overview and terminology
Chris@14 14 *
Chris@14 15 * The Settings Tray module allows blocks to be configured in a sidebar form
Chris@14 16 * without leaving the page. For example:
Chris@14 17 *
Chris@14 18 * - For every block, one can configure whether to display the block title or
Chris@14 19 * not, and optionally override it (block configuration).
Chris@14 20 * - For menu blocks, one can configure which menu levels to display (block
Chris@14 21 * configuration) but also the menu itself (menu configuration).
Chris@14 22 * - For the site branding block, one can change which branding elements to
Chris@14 23 * display (block configuration), but also the site name and slogan (simple
Chris@14 24 * configuration).
Chris@14 25 *
Chris@14 26 * Block visibility conditions are not included the sidebar form.
Chris@14 27 *
Chris@0 28 * @section sec_api The API: the form in the Settings Tray
Chris@0 29 *
Chris@14 30 * By default, the Settings Tray shows any block's built-in form in the
Chris@14 31 * off-canvas dialog.
Chris@14 32 *
Chris@14 33 * @see core/misc/dialog/off-canvas.es6.js
Chris@14 34 *
Chris@0 35 * However, many blocks would benefit from a tailored form which either:
Chris@0 36 * - limits the form items displayed in the Settings Tray to only items that
Chris@0 37 * affect the content of the rendered block
Chris@0 38 * - adds additional form items to edit configuration that is rendered by the
Chris@0 39 * block. See \Drupal\settings_tray\Form\SystemBrandingOffCanvasForm which
Chris@0 40 * adds site name and slogan configuration.
Chris@0 41 *
Chris@0 42 * These can be used to provide a better experience, so that the Settings Tray
Chris@0 43 * only displays what the user will expect to change when editing the block.
Chris@0 44 *
Chris@0 45 * Each block plugin can specify which form to use in the Settings Tray dialog
Chris@0 46 * in its plugin annotation:
Chris@0 47 * @code
Chris@0 48 * forms = {
Chris@0 49 * "settings_tray" = "\Drupal\some_module\Form\MyBlockOffCanvasForm",
Chris@0 50 * },
Chris@0 51 * @endcode
Chris@0 52 *
Chris@0 53 * In some cases, a block's content is not configurable (for example, the title,
Chris@14 54 * main content, and help blocks). Such blocks can opt out of providing a
Chris@14 55 * settings_tray form:
Chris@0 56 * @code
Chris@0 57 * forms = {
Chris@0 58 * "settings_tray" = FALSE,
Chris@0 59 * },
Chris@0 60 * @endcode
Chris@0 61 *
Chris@14 62 * Finally, blocks that do not specify a settings_tray form using the annotation
Chris@0 63 * above will automatically have it set to their plugin class. For example, the
Chris@0 64 * "Powered by Drupal" block plugin
Chris@14 65 * (\Drupal\system\Plugin\Block\SystemPoweredByBlock) automatically gets this
Chris@14 66 * added to its annotation:
Chris@0 67 * @code
Chris@0 68 * forms = {
Chris@0 69 * "settings_tray" = "\Drupal\system\Plugin\Block\SystemPoweredByBlock",
Chris@0 70 * },
Chris@0 71 * @endcode
Chris@0 72 *
Chris@0 73 * Therefore, the entire Settings Tray API is just this annotation: it controls
Chris@0 74 * what the Settings Tray does for a given block.
Chris@0 75 *
Chris@0 76 * @see settings_tray_block_alter()
Chris@0 77 * @see \Drupal\Tests\settings_tray\Functional\SettingsTrayBlockTest::testPossibleAnnotations()
Chris@0 78 *
Chris@0 79 * @}
Chris@0 80 */