Updated to Drupal 8.5. Core Media not yet in use.

[yaffs-website] / web / core / modules / settings_tray / settings_tray.api.php

diff --git a/web/core/modules/settings_tray/settings_tray.api.php b/web/core/modules/settings_tray/settings_tray.api.php
index 05297f0d4b92f05420cd32842c50e3b335eade4f..1221daf3b307d97585e69051b4ae45751cd837e6 100644 (file)
--- a/web/core/modules/settings_tray/settings_tray.api.php
+++ b/web/core/modules/settings_tray/settings_tray.api.php
@@ -10,9 +10,28 @@
  * @{
  * Settings Tray API
  *
+ * @section sec_overview 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.
+ *
  * @section sec_api The API: the form in the Settings Tray
  *
- * By default, every block will show its built-in form in the Settings Tray.
+ * By default, the Settings Tray shows any block's built-in form in the
+ * off-canvas dialog.
+ *
+ * @see core/misc/dialog/off-canvas.es6.js
+ *
  * 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
@@ -32,19 +51,19 @@
  * @endcode
  *
  * 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 an
- * off-canvas form:
+ * main content, and help blocks). Such blocks can opt out of providing a
+ * settings_tray form:
  * @code
  * forms = {
  *   "settings_tray" = FALSE,
  * },
  * @endcode
  *
- * Finally, blocks that do not specify an off-canvas form using the annotation
+ * 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:
+ * (\Drupal\system\Plugin\Block\SystemPoweredByBlock) automatically gets this
+ * added to its annotation:
  * @code
  * forms = {
  *   "settings_tray" = "\Drupal\system\Plugin\Block\SystemPoweredByBlock",