sub-topic @BootstrapSetting

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 ./THEMENAME/src/Plugin/Setting/THEMENAME/Accessibility/SkipLink.php with the following contents:

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

use Drupal\bootstrap\Annotation\BootstrapSetting;
use Drupal\bootstrap\Plugin\Setting\SettingBase;
use Drupal\Core\Annotation\Translation;

/**
 * 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"  = "http://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.

Parent topics

Source docs/plugins/Setting.md (line 4)

Classes

Namesort descending Description
BootstrapSetting Defines a BootstrapSetting annotation object.
Breadcrumb The "breadcrumb" theme setting.
BreadcrumbHome The "breadcrumb_home" theme setting.
BreadcrumbTitle The "breadcrumb_title" theme setting.
ButtonColorize The "button_colorize" theme setting.
ButtonIconize The "button_iconize" theme setting.
ButtonSize The "button_size" theme setting.
CdnCustomCss The "cdn_custom_css" theme setting.
CdnCustomCssMin The "cdn_custom_css_min" theme setting.
CdnCustomJs The "cdn_custom_js" theme setting.
CdnCustomJsMin The "cdn_custom_js_min" theme setting.
CdnJsdelivrTheme The "cdn_jsdelivr_theme" theme setting.
CdnJsdelivrVersion The "cdn_jsdelivr_version" theme setting.
CdnProvider The "cdn_provider" theme setting.
FluidContainer Container theme settings.
FormsHasErrorValueToggle The "forms_has_error_value_toggle" theme setting.
FormsRequiredHasError The "forms_required_has_error" theme setting.
FormsSmartDescriptions The "forms_smart_descriptions" theme setting.
FormsSmartDescriptionsAllowedTags The "forms_smart_descriptions_allowed_tags" theme setting.
FormsSmartDescriptionsLimit The "forms_smart_descriptions_limit" theme setting.
ImageResponsive The "image_responsive" theme setting.
ImageShape The "image_shape" theme setting.
IncludeDeprecated The "include_deprecated" theme setting.
ModalAnimation The "modal_animation" theme setting.
ModalBackdrop The "modal_backdrop" theme setting.
ModalEnabled The "modal_enabled" theme setting.
ModalKeyboard The "modal_keyboard" theme setting.
ModalShow The "modal_show" theme setting.
ModalSize The "modal_size" theme setting.
NavbarInverse The "navbar_inverse" theme setting.
NavbarPosition The "navbar_position" theme setting.
PopoverAnimation The "popover_animation" theme setting.
PopoverContainer The "popover_container" theme setting.
PopoverContent The "popover_content" theme setting.
PopoverDelay The "popover_delay" theme setting.
PopoverEnabled The "popover_enabled" theme setting.
PopoverHtml The "popover_html" theme setting.
PopoverPlacement The "popover_placement" theme setting.
PopoverSelector The "popover_selector" theme setting.
PopoverTitle The "popover_title" theme setting.
PopoverTrigger The "popover_trigger" theme setting.
PopoverTriggerAutoclose The "popover_trigger_autoclose" theme setting.
RegionWells The "region_wells" theme setting.
Schemas The "schemas" theme setting.
SettingBase Base class for a setting.
SettingManager Manages discovery and instantiation of Bootstrap theme settings.
SuppressDeprecatedWarnings The "suppress_deprecated_warnings" theme setting.
SystemThemeSettings Implements hook_form_system_theme_settings_alter().
TableBordered The "table_bordered" theme setting.
TableCondensed The "table_condensed" theme setting.
TableHover The "table_hover" theme setting.
TableResponsive The "table_responsive" theme setting.
TableStriped The "table_striped" theme setting.
TooltipAnimation The "tooltip_animation" theme setting.
TooltipContainer The "tooltip_container" theme setting.
TooltipDelay The "tooltip_delay" theme setting.
TooltipEnabled The "tooltip_enabled" theme setting.
TooltipHtml The "tooltip_html" theme setting.
TooltipPlacement The "tooltip_placement" theme setting.
TooltipSelector The "tooltip_selector" theme setting.
TooltipTrigger The "tooltip_trigger" theme setting.

Interfaces

Namesort descending Description
SettingInterface Defines the interface for an object oriented theme setting plugin.