www.aleph1.co.uk Git - yaffs-website/blob - web/themes/contrib/bootstrap/docs/plugins/Setting.md

   1 <!-- @file Documentation for the @BootstrapSetting annotated plugin. -->
   2 <!-- @defgroup -->
   3 <!-- @ingroup -->
   4 # @BootstrapSetting
   5
   6 - [Create a plugin](#create)
   7 - [Rebuild the cache](#rebuild)
   8 - [Public Methods](#methods)
   9
  10 ## Create a plugin {#create}
  11
  12 We will use `SkipLink` as our first `@BootstrapSetting` plugin to create. In
  13 this example we want our sub-theme to specify a different skip link anchor id
  14 to change in the Theme Settings interface altering the default of
  15 `#main-content`.
  16
  17 Replace all of the following instances of `THEMENAME` with the actual machine
  18 name of your sub-theme.
  19
  20 Create a file at
  21 `./THEMENAME/src/Plugin/Setting/THEMENAME/Accessibility/SkipLink.php`
  22 with the following contents:
  23
  24 ```php
  25 <?php
  26 namespace Drupal\THEMENAME\Plugin\Setting\THEMENAME\Accessibility;
  27
  28 use Drupal\bootstrap\Plugin\Setting\SettingBase;
  29
  30 /**
  31  * The "THEMENAME_skip_link_id" theme setting.
  32  *
  33  * @ingroup plugins_setting
  34  *
  35  * @BootstrapSetting(
  36  *   id = "THEMENAME_skip_link_id",
  37  *   type = "textfield",
  38  *   title = @Translation("Anchor ID for the ""skip link"""),
  39  *   defaultValue = "main-content",
  40  *   description = @Translation("Specify the HTML ID of the element that the accessible-but-hidden ""skip link"" should link to. (<a href="":link"" target=""_blank"">Read more about skip links</a>.)",
  41  *   arguments = { ":link"  = "https://www.drupal.org/node/467976" }),
  42  *   groups = {
  43  *     "THEMENAME" = "THEMETITLE",
  44  *     "accessibility" = @Translation("Accessibility"),
  45  *   },
  46  * )
  47  */
  48 class SkipLink extends SettingBase {}
  49 ?>
  50 ```
  51
  52 Helpfully Bootstrap adds a global `theme` variable added to every template
  53 in `Bootstrap::preprocess()`.
  54
  55 This variable can now simply be called in the `html.html.twig` file with the
  56 following contents:
  57
  58 ```twig
  59 <a href="#{{ theme.settings.THEMENAME_skip_link_id }}"
  60   class="visually-hidden focusable skip-link">
  61   {{ 'Skip to main content'|t }}
  62 </a>
  63 ```
  64
  65 In addition, the `page.html.twig` file will also need to be adjusted for this to
  66 work properly with the new anchor id.
  67
  68 ```twig
  69 <a id="{{ theme.settings.THEMENAME_skip_link_id }}"></a>
  70 ```
  71
  72 ## Rebuild the cache {#rebuild}
  73
  74 Once you have saved, you must rebuild your cache for this new plugin to be
  75 discovered. This must happen anytime you make a change to the actual file name
  76 or the information inside the `@BootstrapSetting` annotation.
  77
  78 To rebuild your cache, navigate to `admin/config/development/performance` and
  79 click the `Clear all caches` button. Or if you prefer, run `drush cr` from the
  80 command line.
  81
  82 Voilà! After this, you should have a fully functional `@BootstrapSetting`
  83 plugin!
  84
  85 ## Public Methods {#methods}
  86
  87 Now that we covered how to create a basic `@BootstrapSetting` plugin, we can
  88 discuss how to customize a setting to fulfill a range of requirements.
  89
  90 The `@BootstrapSetting` is implemented through the base class `SettingBase`
  91 which provides a variety of public methods to assist in the customization of
  92 a plugin.
  93
  94 #### SettingBase::alterForm(array &$form, FormStateInterface $form_state, $form_id = NULL)
  95 #### SettingBase::alterFormElement(Element $form, FormStateInterface $form_state, $form_id = NULL)
  96
  97 Both of these methods provide a way for you to alter the setting's form render
  98 array element as well as the form state object.
  99
 100 The first method is similar to any standard `hook_form_alter`.
 101
 102 However, the second method passes the `$form` argument as an instance of the
 103 `Element` utility helper class. This will allow easier manipulation of all the
 104 elements in this method. Using this method is preferable and considered
 105 "Best Practice".
 106
 107 Two useful examples to study:
 108
 109 - CDNProvider::alterFormElement
 110 - RegionWells::alterFormElement
 111
 112 #### SettingBase::drupalSettings()
 113
 114 This method provides a way for you to determine whether a theme setting should
 115 be added to the `drupalSettings` JavaScript variable. Please note that by
 116 default this is set to `FALSE` to prevent any potentially sensitive information
 117 from being leaked.
 118
 119 #### SettingBase::getCacheTags()
 120
 121 This method provides a way for you to add cache tags that when the instantiated
 122 class is modified the associated cache tags will be invalidated. This is
 123 incredibly useful for example with CDNCustomCss::getCacheTags() which returns an
 124 array of `library_info`. So when a CdnProvider::getCacheTags() instantiated
 125 plugin changes the `library_info` cache tag will be invalidated automatically.
 126
 127 It is important to note that the invalidation occurs because the base theme
 128 loads external resources using libraries by altering the libraries it defines
 129 based on settings in LibraryInfo::alter().
 130
 131 #### SettingBase::getGroupElement(Element $form, FormStateInterface $form_state)
 132
 133 This method provides a way for you to retrieve the last group (fieldset /
 134 details form element) the setting is nested in; based on the plugin definition.
 135
 136 #### SettingBase::getGroups()
 137
 138 This method retrieves the associative array of groups; based on the plugin
 139 definition. It's keyed by the group machine name and its value is the
 140 translatable label.
 141
 142 #### SettingBase::getSettingElement(Element $form, FormStateInterface $form_state)
 143
 144 This method provides a way for you to retrieve the form element that was
 145 automatically generated by the base theme for the setting; based on the plugin
 146 definition.
 147
 148 #### SettingBase::submitForm(array &$form, FormStateInterface $form_state)
 149 #### SettingBase::submitFormElement(Element $form, FormStateInterface $form_state)
 150
 151 Both of these methods provide a way for you to alter the submitted values
 152 stored in the form state object before the setting's value is ultimately stored
 153 in configuration by the base theme, which is performed automatically for you.
 154
 155 Two useful example to study:
 156
 157 - RegionWells::submitFormElement
 158
 159 #### SettingBase::validateForm(array &$form, FormStateInterface $form_state)
 160 #### SettingBase::validateFormElement(Element $form, FormStateInterface $form_state)
 161
 162 Both of these methods provide a way for you to validate the setting's form.