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 - ./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
   

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

button_colorize: 1

button_iconize: 1

button_size: ''

General > Container

fluid_container: 0

General > Forms

forms_has_error_value_toggle: 1

forms_required_has_error: 0

forms_smart_descriptions: 1

forms_smart_descriptions_allowed_tags: 'b, code, em, i, kbd, span, strong'

forms_smart_descriptions_limit: '250'

General > Images

image_responsive: 1

image_shape: ''

General > Tables

table_bordered: 0

table_condensed: 0

table_hover: 1

table_striped: 1

table_responsive: -1

Components > Breadcrumbs

breadcrumb: '1'

breadcrumb_home: 0

breadcrumb_title: 1

Components > Navbar

navbar_inverse: 0

navbar_position: ''

Components > Region Wells

region_wells:
  navigation: ''
  navigation_collapsible: ''
  header: ''
  highlighted: ''
  help: ''
  content: ''
  sidebar_first: ''
  sidebar_second: well
  footer: ''

JavaScript > Modals

modal_enabled: 1

modal_jquery_ui_bridge: 1

modal_animation: 1

modal_backdrop: 'true'

modal_focus_input: 1

modal_keyboard: 1

modal_select_text: 1

modal_show: 1

modal_size: ''

JavaScript > Popovers

popover_enabled: 1

popover_animation: 1

popover_auto_close: 1

popover_container: body

popover_content: ''

popover_delay: '0'

popover_html: 0

popover_placement: right

popover_selector: ''

popover_title: ''

popover_trigger: click

JavaScript > Tooltips

tooltip_enabled: 1

tooltip_animation: 1

tooltip_container: body

tooltip_delay: '0'

tooltip_html: 0

tooltip_placement: 'auto left'

tooltip_selector: ''

tooltip_trigger: hover

CDN (Content Delivery Network)

cdn_provider: jsdelivr

cdn_version: 3.4.1

CDN (Content Delivery Network) > Advanced Cache

cdn_cache_ttl_versions: 604800

cdn_cache_ttl_themes: 604800

cdn_cache_ttl_assets: -1

cdn_cache_ttl_library: -1

CDN (Content Delivery Network) > Custom URLs

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

include_deprecated: 0

suppress_deprecated_warnings: 0

Deprecated

popover_trigger_autoclose: 1

cdn_jsdelivr_version: 3.4.1

cdn_jsdelivr_theme: bootstrap

cdn_custom_css: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.css'

cdn_custom_css_min: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css'

cdn_custom_js: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.js'

cdn_custom_js_min: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.min.js'

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