Adding theme settings (advanced)

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

$form['color'] = array(
  '#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'))) . '',
);

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(
  '#type' => 'radios',
  '#options' => array(
    'no-tabs' => 'No tabs', 
    'rounded-tabs' => 'Rounded tabs', 
    'square-tabs' => 'Square tabs'),
  '#default_value' => theme_get_setting('main_menu_tabs', 'bartik'),
  '#description' => t('When rounded or square tabs are selected, menu link color is overridden and set to #333 for better visibility.'),
);

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:

<?php
function bartik_preprocess_node(&$variables) {
  $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:

<?php 
...
$main_menu_tabs = theme_get_setting('main_menu_tabs', 'bartik'); 
print $main_menu_tabs;
...
?>

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:

<?php
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 have two options:

1. Legacy .info method: You can add a simple line to your .info file: settings[SETTING_NAME] = DEFAULT_VALUE. For Bartik, you’d need to edit the bartik.info file and add this line:
settings[menu_tab_color] = blue

2. Configuration file: You can add default settings in a JSON file inside of a config folder. See details on this method here.

In any of your theme’s PHP files, you can retrieve the value the user set by calling:

<?php
$menu_tab_color = theme_get_setting('menu_tab_color');
?>

Adding additional settings to a new version of your theme

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

1. In the theme's theme-settings.php file, add the new settings to the $form variables.
2. In the theme's .info or config add the new setting, and its default value.

For existing sites that were running the theme before the update, the default value from the .info file will be used until the theme settings form on that site has been saved.