Description
Adds a new theme setting that can be customized using the Theme Customization API. This is a method of the WP_Customize_Manager() class and can only be accessed through the $wp_customize object within the customize_register action hook.
Usage
$wp_customize->add_setting($id, $args);
Parameters
- $id
- (string) (required) A unique slug-like ID for the theme setting.
- Default: None
- $args
- (array) (required) An associative array containing arguments for the setting.
- Default: None
Arguments
- default
- A default value for the setting if none is defined
- type
- Optional. Specifies the TYPE of setting this is. Options are 'option' or 'theme_mod' (defaults to 'theme_mod')
- capability
- Optional. You can define a capability a user must have to modify this setting. Default if not specified:
edit_theme_options
- theme_supports
- Optional. This can be used to hide a setting if the theme lacks support for a specific feature (using add_theme_support).
- transport
- Optional. This can be either 'refresh' (default) or 'postMessage'. Only set this to 'postMessage' if you are writing custom Javascript to control the Theme Customizer's live preview.
- sanitize_callback
- Optional. A function name to call for sanitizing the input value for this setting. The function should be of the form of a standard filter function, where it accepts the input data and returns the sanitized data.
- sanitize_js_callback
- Optional. A function name to call for sanitizing the value for this setting for the purposes of outputting to javascript code. The function should be of the form of a standard filter function, where it accepts the input data and returns the sanitized data. This is only necessary if the data to be sent to the customizer window has a special form.
One way to think of the difference between sanitize_callback and sanitize_js_callback is as input and output. The sanitize_callback will be invoked when data comes from the customizer to the database. The sanitize_js_callback will be invoked when data comes from the database back to the customizer.
Example
Remember that this example assumes you are already working within the customize_register action hook.
$wp_customize->add_setting( 'header_color' , array(
'default' => '#000',
'sanitize_callback' => 'sanitize_hex_color',
) );
Related