DrupalTutorial/themes/bootstrap/docs/plugins/Setting.md

@BootstrapSetting

• Create a plugin
• Rebuild the cache
• Public Methods

Create a plugin

We will use SkipLink as our first @BootstrapSetting plugin to create. In this example we want our sub-theme to specify a different skip link anchor id to change in the Theme Settings interface altering the default of #main-content.

Replace all of the following instances of THEMENAME with the actual machine name of your sub-theme.

Create a file at ./themes/THEMENAME/src/Plugin/Setting/THEMENAME/Accessibility/SkipLink.php with the following contents:

<?php
namespace Drupal\THEMENAME\Plugin\Setting\THEMENAME\Accessibility;

use Drupal\bootstrap\Plugin\Setting\SettingBase;

/**
 * The "THEMENAME_skip_link_id" theme setting.
 *
 * @ingroup plugins_setting
 *
 * @BootstrapSetting(
 *   id = "THEMENAME_skip_link_id",
 *   type = "textfield",
 *   title = @Translation("Anchor ID for the ""skip link"""),
 *   defaultValue = "main-content",
 *   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>.)",
 *   arguments = { ":link"  = "https://www.drupal.org/node/467976" }),
 *   groups = {
 *     "THEMENAME" = "THEMETITLE",
 *     "accessibility" = @Translation("Accessibility"),
 *   },
 * )
 */
class SkipLink extends SettingBase {}
?>

Helpfully Bootstrap adds a global theme variable added to every template in Bootstrap::preprocess().

This variable can now simply be called in the html.html.twig file with the following contents:

<a href="#{{ theme.settings.THEMENAME_skip_link_id }}"
  class="visually-hidden focusable skip-link">
  {{ 'Skip to main content'|t }}
</a>

In addition, the page.html.twig file will also need to be adjusted for this to work properly with the new anchor id.

<a id="{{ theme.settings.THEMENAME_skip_link_id }}"></a>

Rebuild the cache

Once you have saved, you must rebuild your cache for this new plugin to be discovered. This must happen anytime you make a change to the actual file name or the information inside the @BootstrapSetting annotation.

To rebuild your cache, navigate to admin/config/development/performance and click the Clear all caches button. Or if you prefer, run drush cr from the command line.

Voilà! After this, you should have a fully functional @BootstrapSetting plugin!

Public Methods

Now that we covered how to create a basic @BootstrapSetting plugin, we can discuss how to customize a setting to fulfill a range of requirements.

The @BootstrapSetting is implemented through the base class SettingBase which provides a variety of public methods to assist in the customization of a plugin.

SettingBase::alterForm(array &$form, FormStateInterface $form_state, $form_id = NULL)

SettingBase::alterFormElement(Element $form, FormStateInterface $form_state, $form_id = NULL)

Both of these methods provide a way for you to alter the setting's form render array element as well as the form state object.

The first method is similar to any standard hook_form_alter.

However, the second method passes the $form argument as an instance of the Element utility helper class. This will allow easier manipulation of all the elements in this method. Using this method is preferable and considered "Best Practice".

Two useful examples to study:

• CDNProvider::alterFormElement
• RegionWells::alterFormElement

SettingBase::drupalSettings()

This method provides a way for you to determine whether a theme setting should be added to the drupalSettings JavaScript variable. Please note that by default this is set to FALSE to prevent any potentially sensitive information from being leaked.

SettingBase::getCacheTags()

This method provides a way for you to add cache tags that when the instantiated class is modified the associated cache tags will be invalidated. This is incredibly useful for example with CDNCustomCss::getCacheTags() which returns an array of library_info. So when a CdnProvider::getCacheTags() instantiated plugin changes the library_info cache tag will be invalidated automatically.

It is important to note that the invalidation occurs because the base theme loads external resources using libraries by altering the libraries it defines based on settings in LibraryInfo::alter().

SettingBase::getGroupElement(Element $form, FormStateInterface $form_state)

This method provides a way for you to retrieve the last group (fieldset / details form element) the setting is nested in; based on the plugin definition.

SettingBase::getGroups()

This method retrieves the associative array of groups; based on the plugin definition. It's keyed by the group machine name and its value is the translatable label.

SettingBase::getSettingElement(Element $form, FormStateInterface $form_state)

This method provides a way for you to retrieve the form element that was automatically generated by the base theme for the setting; based on the plugin definition.

SettingBase::submitForm(array &$form, FormStateInterface $form_state)

SettingBase::submitFormElement(Element $form, FormStateInterface $form_state)

Both of these methods provide a way for you to alter the submitted values stored in the form state object before the setting's value is ultimately stored in configuration by the base theme, which is performed automatically for you.

Two useful example to study:

• RegionWells::submitFormElement

SettingBase::validateForm(array &$form, FormStateInterface $form_state)

SettingBase::validateFormElement(Element $form, FormStateInterface $form_state)

Both of these methods provide a way for you to validate the setting's form.