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
./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.
Parent topics
Source docs/plugins/Setting.md
Classes
Name | Description |
---|---|
TooltipTrigger | The "tooltip_trigger" theme setting. |
TooltipSelector | The "tooltip_selector" theme setting. |
TooltipPlacement | The "tooltip_placement" theme setting. |
TooltipHtml | The "tooltip_html" theme setting. |
TooltipEnabled | The "tooltip_enabled" theme setting. |
TooltipDelay | The "tooltip_delay" theme setting. |
TooltipContainer | The "tooltip_container" theme setting. |
TooltipAnimation | The "tooltip_animation" theme setting. |
TableStriped | The "table_striped" theme setting. |
TableResponsive | The "table_responsive" theme setting. |
TableHover | The "table_hover" theme setting. |
TableCondensed | The "table_condensed" theme setting. |
TableBordered | The "table_bordered" theme setting. |
SystemThemeSettings | Implements hook_form_system_theme_settings_alter(). |
SuppressDeprecatedWarnings | The "suppress_deprecated_warnings" theme setting. |
SettingManager | Manages discovery and instantiation of Bootstrap theme settings. |
SettingBase | Base class for a setting. |
Schemas | The "schemas" theme setting. |
RegionWells | The "region_wells" theme setting. |
PopoverTriggerAutoclose Deprecated | The "popover_trigger_autoclose" theme setting. |
PopoverTrigger | The "popover_trigger" theme setting. |
PopoverTitle | The "popover_title" theme setting. |
PopoverSelector | The "popover_selector" theme setting. |
PopoverPlacement | The "popover_placement" theme setting. |
PopoverHtml | The "popover_html" theme setting. |
PopoverEnabled | The "popover_enabled" theme setting. |
PopoverDelay | The "popover_delay" theme setting. |
PopoverContent | The "popover_content" theme setting. |
PopoverContainer | The "popover_container" theme setting. |
PopoverAutoClose | The "popover_trigger_autoclose" theme setting. |
PopoverAnimation | The "popover_animation" theme setting. |
NavbarPosition | The "navbar_position" theme setting. |
NavbarInverse | The "navbar_inverse" theme setting. |
ModalSize | The "modal_size" theme setting. |
ModalShow | The "modal_show" theme setting. |
ModalSelectText | The "modal_select_text" theme setting. |
ModalKeyboard | The "modal_keyboard" theme setting. |
ModalJqueryUIBridge | The "modal_jquery_ui_bridge" theme setting. |
ModalFocusInput | The "modal_focus_input" theme setting. |
ModalEnabled | The "modal_enabled" theme setting. |
ModalBackdrop | The "modal_backdrop" theme setting. |
ModalAnimation | The "modal_animation" theme setting. |
IncludeDeprecated | The "include_deprecated" theme setting. |
ImageShape | The "image_shape" theme setting. |
ImageResponsive | The "image_responsive" theme setting. |
FormsSmartDescriptionsLimit | The "forms_smart_descriptions_limit" theme setting. |
FormsSmartDescriptionsAllowedTags | The "forms_smart_descriptions_allowed_tags" theme setting. |
FormsSmartDescriptions | The "forms_smart_descriptions" theme setting. |
FormsRequiredHasError | The "forms_required_has_error" theme setting. |
FormsHasErrorValueToggle | The "forms_has_error_value_toggle" theme setting. |
FluidContainer | Container theme settings. |
CdnVersion | The "cdn_version" theme setting. |
CdnTheme | The "cdn_theme" theme setting. |
CdnProviderBase | A base class for CDN Provider settings. |
CdnProvider | The "cdn_provider" theme setting. |
CdnCustom | The "cdn_custom" theme setting. |
CdnCacheTtlVersions | The "cdn_cache_ttl_versions" theme setting. |
CdnCacheTtlThemes | The "cdn_cache_ttl_themes" theme setting. |
CdnCacheTtlLibrary | The "cdn_cache_ttl_library" theme setting. |
CdnCacheTtlBase | Base class for "cdn_cache_ttl_*" settings. |
CdnCacheTtlAssets | The "cdn_cache_ttl_assets" theme setting. |
ButtonSize | The "button_size" theme setting. |
ButtonIconize | The "button_iconize" theme setting. |
ButtonColorize | The "button_colorize" theme setting. |
BreadcrumbTitle | The "breadcrumb_title" theme setting. |
BreadcrumbHome | The "breadcrumb_home" theme setting. |
Breadcrumb | The "breadcrumb" theme setting. |
BootstrapSetting | Defines a BootstrapSetting annotation object. |
Interfaces
Name | Description |
---|---|
SettingInterface | Defines the interface for an object oriented theme setting plugin. |