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