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:

  1. Install Config - ./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
    
  2. Exported Config - ./CONFIG_DIR/THEMENAME.settings.yml
    This is where theme settings are exported. The CONFIG_DIR is usually a directory located either just inside or outside the DOCROOT of the site. You can read more about this in the link above. This file is automatically generated; DO NOT EDIT MANUALLY.
  3. Active Config - (Database)
    Located in both the config and cache_config tables there will be an entry named THEMENAME.settings. This is where the "active" config is stored. These database entries are automatically generated; DO NOT EDIT MANUALLY.
  4. Overridden Config - ./DOCROOT/sites/default/settings[.local].php
    This is your site's settings[.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
button_colorize
Adds classes to buttons based on their text value.
button_colorize: 1
button_iconize
Adds icons to buttons based on the text value
button_iconize: 1
button_size
Defines the Bootstrap Buttons specific size
button_size: ''

General > Container

Setting name Description and default value
fluid_container
Uses the .container-fluid class instead of .container.
fluid_container: 0

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_has_error_value_toggle: 1
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_required_has_error: 0
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.
forms_smart_descriptions: 1
forms_smart_descriptions_allowed_tags
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_allowed_tags: 'b, code, em, i, kbd, span, strong'
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.
forms_smart_descriptions_limit: '250'

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_responsive: 1
image_shape
Add classes to an <img> element to easily style images in any project.
image_shape: ''

General > Tables

Setting name Description and default value
table_bordered
Add borders on all sides of the table and cells.
table_bordered: 0
table_condensed
Make tables more compact by cutting cell padding in half.
table_condensed: 0
table_hover
Enable a hover state on table rows.
table_hover: 1
table_striped
Add zebra-striping to any table row within the <tbody>.
table_striped: 1
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.
table_responsive: -1

Components > Breadcrumbs

Setting name Description and default value
breadcrumb
Show or hide the Breadcrumbs
breadcrumb: '1'
breadcrumb_home
If your site has a module dedicated to handling breadcrumbs already, ensure this setting is enabled.
breadcrumb_home: 0
breadcrumb_title
If your site has a module dedicated to handling breadcrumbs already, ensure this setting is disabled.
breadcrumb_title: 1

Components > Navbar

Setting name Description and default value
navbar_inverse
Select if you want the inverse navbar style.
navbar_inverse: 0
navbar_position
Determines where the navbar is positioned on the page.
navbar_position: ''

Components > Region Wells

Setting name Description and default value
region_wells
Enable the .well, .well-sm or .well-lg classes for specified regions.
region_wells:
  navigation: ''
  navigation_collapsible: ''
  header: ''
  highlighted: ''
  help: ''
  content: ''
  sidebar_first: ''
  sidebar_second: well
  footer: ''

JavaScript > Modals

Setting name Description and default value
modal_enabled
modal_enabled: 1
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_jquery_ui_bridge: 1
modal_animation
Apply a CSS fade transition to modals.
modal_animation: 1
modal_backdrop
Includes a modal-backdrop element. Alternatively, specify static for a backdrop which doesn't close the modal on click.
modal_backdrop: 'true'
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_focus_input: 1
modal_keyboard
Closes the modal when escape key is pressed.
modal_keyboard: 1
modal_select_text
Enabling this selects the text of the first available and visible input found after it has been focused.
modal_select_text: 1
modal_show
Shows the modal when initialized.
modal_show: 1
modal_size
Defines the modal size between the default, modal-sm and modal-lg.
modal_size: ''

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_enabled: 1
popover_animation
Apply a CSS fade transition to the popover.
popover_animation: 1
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_auto_close: 1
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_container: body
popover_content
Default content value if data-content or data-target attributes are not present.
popover_content: ''
popover_delay
The amount of time to delay showing and hiding the popover (in milliseconds). Does not apply to manual trigger type.
popover_delay: '0'
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_html: 0
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_placement: 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_selector: ''
popover_title
Default title value if title attribute isn't present.
popover_title: ''
popover_trigger
How a popover is triggered.
popover_trigger: click

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_enabled: 1
tooltip_animation
Apply a CSS fade transition to the tooltip.
tooltip_animation: 1
tooltip_container
Appends the tooltip to a specific element. Example: body.
tooltip_container: body
tooltip_delay
The amount of time to delay showing and hiding the tooltip (in milliseconds). Does not apply to manual trigger type.
tooltip_delay: '0'
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_html: 0
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_placement: 'auto left'
tooltip_selector
If a selector is provided, tooltip objects will be delegated to the specified targets.
tooltip_selector: ''
tooltip_trigger
How a tooltip is triggered.
tooltip_trigger: hover

CDN (Content Delivery Network)

Setting name Description and default value
cdn_provider
Choose the CDN Provider used to load Bootstrap resources.
cdn_provider: jsdelivr
cdn_version
Choose a version provided by the CDN Provider.
cdn_version: 3.4.1
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_versions: 604800
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_themes: 604800
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_assets: -1
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_cache_ttl_library: -1

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.
cdn_custom: "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.css
https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css
https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.js
https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.min.js"

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.
include_deprecated: 0
suppress_deprecated_warnings
Enable this setting if you wish to suppress deprecated warning messages.
suppress_deprecated_warnings: 0

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.
popover_trigger_autoclose: 1
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
cdn_jsdelivr_version: 3.4.1
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.
cdn_jsdelivr_theme: bootstrap
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.
cdn_custom_css: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.css'
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.
cdn_custom_css_min: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css'
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.
cdn_custom_js: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.js'
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.
cdn_custom_js_min: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.min.js'
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 (line 4)

Sub-Topics

Name Description
Theme Settings Overview of theme settings for Drupal Bootstrap based themes.