www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/settings_tray/settings_tray.api.php

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