Documentation Level: 
Documentation Status: 
No known problems

Themes can provide specific settings by adding values a structured array in a theme-settings.php file in the theme folder.
In Bartik theme, the file theme-settings.php contains the following:

$form['color'] = array(<br />
  '#markup' => '' . t('This theme supports custom color palettes if the Color module is enabled on the <a href="!url">modules page</a>. Enable the Color module to customize this theme.', array('!url' => url('admin/modules'))) . '',<br />

This code fragment then causes the markup text to be displayed on the theme settings page. This is obviously a very simple, non-interactive result, but themes can use the same technique, built on Form API, to create very complex theme settings forms. The following example shows how a slightly more advanced set of settings could be added to Bartik.

$form['main_menu_tabs'] = array(<br />
  '#type' => 'radios',<br />
  '#options' => array(<br />
    'no-tabs' => 'No tabs', <br />
    'rounded-tabs' => 'Rounded tabs', <br />
    'square-tabs' => 'Square tabs'),<br />
  '#default_value' => theme_get_setting('main_menu_tabs', 'bartik'),<br />
  '#description' => t('When rounded or square tabs are selected, menu link color is overridden and set to #333 for better visibility.'),<br />

This is an array in the standard Backdrop Form API format which provides a form element (with an ID 'main_menu_tabs') which is a radio button set with three options, a default value, and a brief description. When theme-settings.php is saved (and the theme cache cleared), the following would appear on Bartiks settings page:
The results from this form, once "Save theme settings" is clicked, are saved in a config file in Backdrop's default config folder, as THEME_NAME.settings.json.

Getting the settings’ values in your theme files

So now you can store custom settings for your theme, and now need to retrieve them. If for example you were building a custom node template to modify how nodes display, you would have created a node.tpl.php file (or more likely copied Bartik's node.tpl.php file) and modified it to suit. In order to retrieve your new settings in the theme’s template.php or .tpl.php files (in this case you want to retrieve it in your node.tpl.php file), simply use theme_get_setting('my_setting'). See the Backdrop API for details. So in Bartik's template .php file, the following code allows Bartik to retrieve the saved value of 'main_menu_tabs' and inject this into a node template as an available variable:

function bartik_preprocess_node(&$variables) {<br />
  $variables['main_menu_tabs'] = theme_get_setting('main_menu_tabs', 'bartik');

(Note that this variable's value would be now available in node.tpl.php as $main_menu_tabs.)

or if you preferred to retrieve this directly in the node.tpl.php file:

$main_menu_tabs = theme_get_setting('main_menu_tabs', 'bartik');

Altering theme settings programmatically

In theme-settings.php, themes can also use THEMENAME_form_system_theme_settings_alter() hook function. This gives the same power to themes that modules have if they use hook_form_system_theme_settings_alter().

Here’s an example if you wanted to add a textfield:

function foo_form_system_theme_settings_alter(&$form, $form_state) {
  $form['menu_tab_color'] = array(
    '#type'          => 'textfield',
    '#title'         => t('Widget'),
    '#default_value' => theme_get_setting('menu_tab_color'),
    '#description'   => t("Menu tab colors."),

Note the differences to the 'main_menu_tabs' setting above:

  • The form element key is now 'menu_tab_color',
  • The type is a textfield

Your new textfield would be added to the form on the Bartik settings page, together with the main_menu_tabs radio select group.

Setting default values

In order to set the default value for any form element you add, you’ll need to add a simple line to your .info file: settings[SETTING_NAME] = DEFAULT_VALUE. For Bartik, you’d need to edit the file and add this line:
settings[menu_tab_color] = blue
In any of your theme’s PHP files, you can retrieve the value the user set by calling:

= theme_get_setting('menu_tab_color');

Note that theme authors can create complex, dynamic forms using advanced Forms API (auto-completion, collapsible fieldsets) and the JavaScript library, jQuery.

Initializing the default values

Since we can’t guarantee that a user will ever go to the theme settings page, we have to ensure that the default values for our custom settings get initialized.In our template.php file we need to check whether the variables are set or not. If they aren’t set, we need to set them to the default values. We accomplish that by retrieving one of the variables and seeing if it is null.

Add the following code near the top of your template.php file:

 * Initialize theme settings
if (is_null(theme_get_setting('menu_tab_color'))) {
  // Save default theme settings.
  config_set('foo.settings', 'menu_tab_color', 'blue');

  // Force refresh of Backdrop internals.
  theme_get_setting('', TRUE);

Adding additional settings to a new version of your theme

After you have released a 1.0 version of your theme, you will eventually want to add some additional custom settings to the 2.0 version. The process is mostly straight-forward:

  1. In your theme-settings.php file, add the new settings to the $form variables.
  2. In your template.php file, update the initialization code to check for the existence of one of your new settings. For example, if you added several settings, including a menu_tab_width setting, you would change the first line of theInitialize theme settings code to read:
    if (is_null(theme_get_setting('menu_tab_width'))) { // Set default values here. }

This will ensure that the defaults for your newly-added custom settings get added to the saved values of the old custom settings.