yaffs.net 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_api The API: the form in the Settings Tray
  14  *
  15  * By default, every block will show its built-in form in the Settings Tray.
  16  * However, many blocks would benefit from a tailored form which either:
  17  * - limits the form items displayed in the Settings Tray to only items that
  18  *   affect the content of the rendered block
  19  * - adds additional form items to edit configuration that is rendered by the
  20  *   block. See \Drupal\settings_tray\Form\SystemBrandingOffCanvasForm which
  21  *   adds site name and slogan configuration.
  22  *
  23  * These can be used to provide a better experience, so that the Settings Tray
  24  * only displays what the user will expect to change when editing the block.
  25  *
  26  * Each block plugin can specify which form to use in the Settings Tray dialog
  27  * in its plugin annotation:
  28  * @code
  29  * forms = {
  30  *   "settings_tray" = "\Drupal\some_module\Form\MyBlockOffCanvasForm",
  31  * },
  32  * @endcode
  33  *
  34  * In some cases, a block's content is not configurable (for example, the title,
  35  * main content, and help blocks). Such blocks can opt out of providing an
  36  * off-canvas form:
  37  * @code
  38  * forms = {
  39  *   "settings_tray" = FALSE,
  40  * },
  41  * @endcode
  42  *
  43  * Finally, blocks that do not specify an off-canvas form using the annotation
  44  * above will automatically have it set to their plugin class. For example, the
  45  * "Powered by Drupal" block plugin
  46  * (\Drupal\system\Plugin\Block\SystemPoweredByBlock) automatically gets
  47  * this added to its annotation:
  48  * @code
  49  * forms = {
  50  *   "settings_tray" = "\Drupal\system\Plugin\Block\SystemPoweredByBlock",
  51  * },
  52  * @endcode
  53  *
  54  * Therefore, the entire Settings Tray API is just this annotation: it controls
  55  * what the Settings Tray does for a given block.
  56  *
  57  * @see settings_tray_block_alter()
  58  * @see \Drupal\Tests\settings_tray\Functional\SettingsTrayBlockTest::testPossibleAnnotations()
  59  *
  60  * @}
  61  */