sub-topic Theme Settings
Drupal 8 introduced the config system.
Theme settings have now become quite more complex due to how and where they are stored and at what point in the process they are accessed.
There are essentially four places where theme settings do or could reside:
-
Install Config -
./themes/THEMENAME/config/install/THEMENAME.settings.yml
This is the install config only. They will only be set upon the initial installation of a theme. This is not like previous Drupal implementations where changes made here are reflected after a cache rebuild. The only way to make changes made to this file be used after a theme has been installed is to completely uninstall and reinstall the theme. To supply default values when a theme is installed, create the file named above and add the following:# Install settings (these are only set once). SETTING_NAME: SETTING_VALUE
-
Exported Config -
./CONFIG_DIR/THEMENAME.settings.yml
This is where theme settings are exported. TheCONFIG_DIR
is usually a directory located either just inside or outside theDOCROOT
of the site. You can read more about this in the link above. This file is automatically generated; DO NOT EDIT MANUALLY. -
Active Config -
(Database)
Located in both theconfig
andcache_config
tables there will be an entry namedTHEMENAME.settings
. This is where the "active" config is stored. These database entries are automatically generated; DO NOT EDIT MANUALLY. -
Overridden Config -
./DOCROOT/sites/default/settings[.local].php
This is your site'ssettings[.local].php
file. Despite its path/filename, anything stored in the$config
variable does not supply default values. These values actually override any exported or active config. While it is technically possible to specify your config based theme settings here, it is important to remember that this file's main purpose is to supply environmental specific$database
and$settings
values (e.g. local, stage, prod, etc.); not config. Its use to store config based theme settings of any kind here is highly discouraged and not supported by this project. While not an exception, it is important to note that this base-theme does support various theme specific$settings
values, which are not the same as or to be confused with the config based theme settings (read more below).
If you are migrating from older versions of Drupal and need help wrapping your head around the config paradigm shift, think of "Active Config" as the new ".info" file, but specifically for your theme's settings. Because this is config though, you don't edit it manually. Instead, you should navigate to your theme's settings UI in the browser, make and save the desired changes, and then export your config. Your new theme settings will appear in the exported config directory.
If you need to programmatically access or modify a theme's settings, it's best to use this base-theme's APIs. To retrieve a theme setting, use: \Drupal\bootstrap\Theme::getSetting(). To set a theme setting, use: \Drupal\bootstrap\Theme::setSetting():
<?php
use Drupal\bootstrap\Bootstrap;
$theme = Bootstrap::getTheme('THEMENAME');
// Retrieve a theme setting.
$theme->getSetting('my_setting', 'a default value');
// Set a theme setting (saved to config automatically).
$theme->setSetting('my_setting', 'a new value');
General > Buttons
Setting name | Description and default value |
---|---|
Adds classes to buttons based on their text value.
|
|
Adds icons to buttons based on the text value
|
|
Defines the Bootstrap Buttons specific size
|
General > Container
Setting name | Description and default value |
---|---|
fluid_container |
Uses the
.container-fluid class instead of .container .
|
General > Forms
Setting name | Description and default value |
---|---|
forms_has_error_value_toggle |
If an element has a
.has-error class attached to it, enabling this will automatically remove that class when a value is entered.
|
forms_required_has_error |
If an element in a form is required, enabling this will always display the element with a
.has-error class. This turns the element red and helps in usability for determining which form elements are required to submit the form.
|
forms_smart_descriptions |
Convert descriptions into tooltips (must be enabled) automatically based on certain criteria. This helps reduce the, sometimes unnecessary, amount of noise on a page full of form elements.
|
Prevents descriptions from becoming tooltips by checking for HTML not in the list above (i.e. links). Separate by commas. To disable this filtering criteria, leave an empty value.
|
|
forms_smart_descriptions_limit |
Prevents descriptions from becoming tooltips by checking the character length of the description (HTML is not counted towards this limit). To disable this filtering criteria, leave an empty value.
|
General > Images
Setting name | Description and default value |
---|---|
image_responsive |
Images in Bootstrap 3 can be made responsive-friendly via the addition of the
.img-responsive class. This applies max-width: 100%; and height: auto; to the image so that it scales nicely to the parent element.
|
image_shape |
Add classes to an
<img> element to easily style images in any project.
|
General > Tables
Setting name | Description and default value |
---|---|
table_bordered |
Add borders on all sides of the table and cells.
|
table_condensed |
Make tables more compact by cutting cell padding in half.
|
table_hover |
Enable a hover state on table rows.
|
table_striped |
Add zebra-striping to any table row within the
<tbody> .
|
table_responsive |
Wraps tables with
.table-responsive to make them horizontally scroll when viewing them on devices under 768px. When viewing on devices larger than 768px, you will not see a difference in the presentational aspect of these tables. The Automatic option will only apply this setting for front-end facing tables, not the tables in administrative areas.
|
Components > Breadcrumbs
Setting name | Description and default value |
---|---|
Show or hide the Breadcrumbs
|
|
If your site has a module dedicated to handling breadcrumbs already, ensure this setting is enabled.
|
|
If your site has a module dedicated to handling breadcrumbs already, ensure this setting is disabled.
|
Components > Navbar
Setting name | Description and default value |
---|---|
Select if you want the inverse navbar style.
|
|
Determines where the navbar is positioned on the page.
|
Components > Region Wells
Setting name | Description and default value |
---|---|
region_wells |
Enable the
.well , .well-sm or .well-lg classes for specified regions.
|
JavaScript > Modals
Setting name | Description and default value |
---|---|
modal_enabled |
|
modal_jquery_ui_bridge |
Enabling this replaces the core/jquery.ui.dialog dependency in the core/drupal.dialog library with a jQuery UI Dialog widget bridge. This bridge adds support to Bootstrap Modals so that it may interpret jQuery UI Dialog functionality.
|
modal_animation |
Apply a CSS fade transition to modals.
|
modal_backdrop |
Includes a modal-backdrop element. Alternatively, specify
static for a backdrop which doesn't close the modal on click.
|
modal_focus_input |
Enabling this focuses on the first available and visible input found in the modal after it's opened. If no element is found, the close button (if visible) is focused instead.
|
modal_keyboard |
Closes the modal when escape key is pressed.
|
modal_select_text |
Enabling this selects the text of the first available and visible input found after it has been focused.
|
modal_show |
Shows the modal when initialized.
|
modal_size |
Defines the modal size between the default,
modal-sm and modal-lg .
|
JavaScript > Popovers
Setting name | Description and default value |
---|---|
popover_enabled |
Elements that have the
data-toggle="popover" attribute set will automatically initialize the popover upon page load. WARNING: This feature can sometimes impact performance. Disable if pages appear to hang after load.
|
popover_animation |
Apply a CSS fade transition to the popover.
|
popover_auto_close |
If enabled, the active popover will automatically close when it loses focus, when a click occurs anywhere in the DOM (outside the popover), the escape key (ESC) is pressed or when another popover is opened.
|
popover_container |
Appends the popover to a specific element. Example:
body . This option is particularly useful in that it allows you to position the popover in the flow of the document near the triggering element - which will prevent the popover from floating away from the triggering element during a window resize.
|
popover_content |
Default content value if
data-content or data-target attributes are not present.
|
popover_delay |
The amount of time to delay showing and hiding the popover (in milliseconds). Does not apply to manual trigger type.
|
popover_html |
Insert HTML into the popover. If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.
|
popover_placement |
Where to position the popover. When
auto is specified, it will dynamically reorient the popover. For example, if placement is auto left , the popover will display to the left when possible, otherwise it will display right.
|
popover_selector |
If a selector is provided, tooltip objects will be delegated to the specified targets. In practice, this is used to enable dynamic HTML content to have popovers added.
|
popover_title |
Default title value if
title attribute isn't present.
|
popover_trigger |
How a popover is triggered.
|
JavaScript > Tooltips
Setting name | Description and default value |
---|---|
tooltip_enabled |
Elements that have the
data-toggle="tooltip" attribute set will automatically initialize the tooltip upon page load. WARNING: This feature can sometimes impact performance. Disable if pages appear to "hang" after load.
|
tooltip_animation |
Apply a CSS fade transition to the tooltip.
|
tooltip_container |
Appends the tooltip to a specific element. Example:
body .
|
tooltip_delay |
The amount of time to delay showing and hiding the tooltip (in milliseconds). Does not apply to manual trigger type.
|
tooltip_html |
Insert HTML into the tooltip. If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.
|
tooltip_placement |
Where to position the tooltip. When
auto is specified, it will dynamically reorient the tooltip. For example, if placement is auto left , the tooltip will display to the left when possible, otherwise it will display right.
|
tooltip_selector |
If a selector is provided, tooltip objects will be delegated to the specified targets.
|
tooltip_trigger |
How a tooltip is triggered.
|
CDN (Content Delivery Network)
Setting name | Description and default value |
---|---|
cdn_provider |
Choose the CDN Provider used to load Bootstrap resources.
|
cdn_version |
Choose a version provided by the CDN Provider.
|
cdn_theme |
Choose a theme provided by the CDN Provider.
|
CDN (Content Delivery Network) > Advanced Cache
Setting name | Description and default value |
---|---|
cdn_cache_ttl_versions |
The length of time to cache the CDN verions before requesting them from the API again.
|
cdn_cache_ttl_themes |
The length of time to cache the CDN themes (if applicable) before requesting them from the API again.
|
cdn_cache_ttl_assets |
The length of time to cache the parsing and processing of CDN assets before rebuilding them again. Note: any change to CDN values automatically triggers a new build.
|
cdn_cache_ttl_library |
The length of time to cache the theme's library alterations before rebuilding them again. Note: any change to CDN values automatically triggers a new build.
|
CDN (Content Delivery Network) > Custom URLs
Setting name | Description and default value |
---|---|
cdn_custom |
One complete URL per line. All URLs are validated and parsed to determine available version(s) and/or theme(s). A URL can be any file ending in
.css or .js (with matching response MIME type). Minified URLs can also be supplied and the will be used automatically.
|
Advanced
Setting name | Description and default value |
---|---|
include_deprecated |
Enabling this setting will include any
deprecated.php file found in your theme or base themes.
|
suppress_deprecated_warnings |
Enable this setting if you wish to suppress deprecated warning messages.
|
Deprecated
Setting name | Description and default value |
---|---|
popover_trigger_autoclose |
Will automatically close the current popover if a click occurs anywhere else other than the popover element.
Deprecated since 8.x-3.14 - Replaced with new setting. Will be removed in a future release. (see: popover_auto_close)
|
cdn_jsdelivr_version |
Choose the Bootstrap version from jsdelivr
Deprecated since 8.x-3.18 - Replaced with new setting. Will be removed in a future release. (see: cdn_version)
|
cdn_jsdelivr_theme |
Choose the Example Theme provided by Bootstrap or one of the Bootswatch themes.
Deprecated since 8.x-3.18 - Replaced with new setting. Will be removed in a future release. (see: cdn_theme)
|
cdn_custom_css |
It is best to use
https protocols here as it will allow more flexibility if the need ever arises.
Deprecated since 8.x-3.18 - Replaced with new setting. Will be removed in a future release. (see: cdn_custom)
|
cdn_custom_css_min |
Additionally, you can provide the minimized version of the file. It will be used instead if site aggregation is enabled.
Deprecated since 8.x-3.18 - Replaced with new setting. Will be removed in a future release. (see: cdn_custom)
|
cdn_custom_js |
It is best to use
https protocols here as it will allow more flexibility if the need ever arises.
Deprecated since 8.x-3.18 - Replaced with new setting. Will be removed in a future release. (see: cdn_custom)
|
cdn_custom_js_min |
Additionally, you can provide the minimized version of the file. It will be used instead if site aggregation is enabled.
Deprecated since 8.x-3.18 - Replaced with new setting. Will be removed in a future release. (see: cdn_custom)
|
Environmental Theme Settings
These settings are not config based and cannot be set via the UI. They can
only be set in your site's settings[.local].php
file. They are intended to be
used only for local development purposes:
Development Mode
This indicates that theme is in "development" mode:
<?php
$settings['theme.dev'] = TRUE;
While this setting doesn't really do much on its own, its primary function is intended to help with sub-theming. This adds variables that can be accessed elsewhere in your code:
PHP
<?php
use Drupal\bootstrap\Bootstrap;
/**
* Implements hook_preprocess_HOOK().
*/
function THEMENAME_preprocess_page(&$variables) {
// Preprocess hooks already have this in the "theme" array.
// This is also passed to the Twig template (see below).
if ($variables['theme']['dev']) {
// Do something here.
}
}
/**
* Implements hook_js_settings_alter().
*/
function THEMENAME_js_settings_alter(array &$settings, AttachedAssetsInterface $assets) {
// In other procedural functions, use the Bootstrap helper method to retrieve
// the theme and then access the method there.
$theme = Bootstrap::getTheme();
if ($theme->isDev()) {
// Do something here.
}
}
In Drupal Bootstrap based plugins, there is a theme
property already in the
plugin instance that can be accessed (e.g. $this->theme->isDev()
).
Twig
{% if theme.dev %}
{# Do something here. #}
{% endif %}
JavaScript
var theme = drupalSettings['THEMENAME'] || {};
if (theme.dev) {
// Do something here.
}
Livereload
This automatically adds livereload to the page. Supply one of the following:
<?php
// Enable default value: //127.0.0.1:35729/livereload.js.
$settings['theme.livereload'] = TRUE;
// Or, set just the port number: //127.0.0.1:12345/livereload.js.
$settings['theme.livereload'] = 12345;
// Or, Set an explicit URL.
$settings['theme.livereload'] = '//127.0.0.1:35729/livereload.js';
Parent topics
Source docs/Theme-Settings.md
Sub-Topics
Name | Description |
---|---|
Theme Settings | Overview of theme settings for Drupal Bootstrap based themes. |