Theme Settings API

Make provides a lot of customization options through the Customizer, and each of these is represented by a “setting”. A setting consists of an ID that is tied to a particular value. When the theme uses that setting, in a template for example, it needs to first retrieve the value, and use a default value as a backup if that setting hasn’t been customized by the user yet. Then it needs to make sure the value retrieved from the database is valid, by “sanitizing” it, so it won’t produce an unexpected result in the template.

Normally the process looks something like this:

$header_text = sanitize_text_field( get_theme_mod( 'header-text', 'Default header text' ) );

The get_theme_mod() call’s first parameter is the setting’s ID, and the second is the default value to use. Then the whole thing is wrapped in the sanitizing function. If the header text setting was used in multiple places in the theme, the sanitizing function and the default value would have to be specified each time.

As of version 1.7, Make has a Theme Settings API that simplifies this by using setting definitions to keep the defaults and sanitizing functions in one place. So from the example above, the header text would be defined like this:

array(
	'header-text' => array(
		'default'  => 'Default header text',
		'sanitize' => 'sanitize_text_field'
	)
);

Then, to retrieve the header text value anywhere in the theme, you simply need to do this:

$header_text = make_get_thememod_value( 'header-text' );

This takes care of providing the default value if no other value is available, and sanitizing the value for use in the theme.

The Theme Settings API also provides a way to modify existing setting definitions, or add your own.

---

Example: Updating setting defaults

function childtheme_update_setting_defaults() {
	make_update_thememod_setting_definition(
		'layout-post-sidebar-left',
		array(
			'default' => true,
		)
	);
	
	make_update_thememod_setting_definition(
		'color-primary',
		array(
			'default' => '#3070d1',
		)
	);
}

add_action( 'make_settings_thememod_loaded', 'childtheme_update_setting_defaults' );

In the above example, the make_update_thememod_setting_definition() function takes two parameters. The first is the ID of the setting. The second is the array of setting properties. In this case, existing settings are being updated, so only the properties that are being changed need to be included.

---

Contexts

Some settings require different sanitize methods for different contexts. For example, if a setting value is a URL, it should be sanitized with esc_url() before displaying it in a link, but it should be sanitized with esc_url_raw() before storing it in the database. Setting definitions account for this by specifying multiple sanitize callbacks:

array(
	'header-background-image' => array(
		'default'           => '',
		'sanitize'          => 'esc_url',
		'sanitize_database' => 'esc_url_raw',
	)
)

The Theme Settings API’s set_value() method uses the “database” context when sanitizing the value before storing it in the database. If a setting doesn’t have a callback for the specified context, the standard sanitize callback is used instead.

The get_value() method has an optional parameter for specifying a context. Example:

Make()->thememod()->get_value( 'header-background-image', 'database' );

This also works with the global template function:

make_get_thememod_value( 'header-background-image', 'database' );

---

Choice Sets

Some settings need to be limited to a value that comes from a specific set of values, rather than having an arbitrary value. These settings have an extra definition property called choice_set_id. Make has a Choices API for managing these choice sets, which you can read about here.