3 * Customize Setting Class
6 * @subpackage Customize
10 class WP_Customize_Setting {
14 public $type = 'theme_mod';
15 public $capability = 'edit_theme_options';
16 public $theme_supports = '';
18 public $transport = 'refresh';
20 public $sanitize_callback = '';
21 public $sanitize_js_callback = '';
23 protected $id_data = array();
24 private $_post_value; // Cached, sanitized $_POST value.
31 * @param string $id An specific ID of the setting. Can be a
32 * theme mod or option name.
33 * @param array $args Setting arguments.
35 function __construct( $manager, $id, $args = array() ) {
36 $keys = array_keys( get_class_vars( __CLASS__ ) );
37 foreach ( $keys as $key ) {
38 if ( isset( $args[ $key ] ) )
39 $this->$key = $args[ $key ];
42 $this->manager = $manager;
45 // Parse the ID for array keys.
46 $this->id_data[ 'keys' ] = preg_split( '/\[/', str_replace( ']', '', $this->id ) );
47 $this->id_data[ 'base' ] = array_shift( $this->id_data[ 'keys' ] );
50 $this->id = $this->id_data[ 'base' ];
51 if ( ! empty( $this->id_data[ 'keys' ] ) )
52 $this->id .= '[' . implode( '][', $this->id_data[ 'keys' ] ) . ']';
54 if ( $this->sanitize_callback )
55 add_filter( "customize_sanitize_{$this->id}", $this->sanitize_callback, 10, 2 );
57 if ( $this->sanitize_js_callback )
58 add_filter( "customize_sanitize_js_{$this->id}", $this->sanitize_js_callback, 10, 2 );
64 * Handle previewing the setting.
68 public function preview() {
69 switch( $this->type ) {
71 add_filter( 'theme_mod_' . $this->id_data[ 'base' ], array( $this, '_preview_filter' ) );
74 if ( empty( $this->id_data[ 'keys' ] ) )
75 add_filter( 'pre_option_' . $this->id_data[ 'base' ], array( $this, '_preview_filter' ) );
77 add_filter( 'option_' . $this->id_data[ 'base' ], array( $this, '_preview_filter' ) );
78 add_filter( 'default_option_' . $this->id_data[ 'base' ], array( $this, '_preview_filter' ) );
82 do_action( 'customize_preview_' . $this->id );
87 * Callback function to filter the theme mods and options.
91 * @param mixed Old value.
92 * @return mixed New or old value.
94 public function _preview_filter( $original ) {
95 return $this->multidimensional_replace( $original, $this->id_data[ 'keys' ], $this->post_value() );
99 * Set the value of the parameter for a specific theme.
103 * @return bool False if cap check fails or value isn't set.
105 public final function save() {
106 $value = $this->post_value();
108 if ( ! $this->check_capabilities() || ! isset( $value ) )
111 do_action( 'customize_save_' . $this->id_data[ 'base' ] );
113 $this->update( $value );
117 * Fetches, validates, and sanitizes the $_POST value.
121 * @param $default mixed A default value which is used as a fallback. Default is null.
122 * @return mixed Either the default value on failure or sanitized value.
124 public final function post_value( $default = null ) {
125 if ( isset( $this->_post_value ) )
126 return $this->_post_value;
128 $result = $this->manager->post_value( $this );
130 if ( isset( $result ) )
131 return $this->_post_value = $result;
141 * @param $value mixed The value to sanitize.
142 * @return mixed Null if an input isn't valid, otherwise the sanitized value.
144 public function sanitize( $value ) {
145 $value = stripslashes_deep( $value );
146 return apply_filters( "customize_sanitize_{$this->id}", $value, $this );
150 * Set the value of the parameter for a specific theme.
154 * @param $value mixed The value to update.
155 * @return mixed The result of saving the value.
157 protected function update( $value ) {
158 switch( $this->type ) {
160 return $this->_update_theme_mod( $value );
163 return $this->_update_option( $value );
166 return do_action( 'customize_update_' . $this->type, $value );
171 * Update the theme mod from the value of the parameter.
175 * @param $value mixed The value to update.
176 * @return mixed The result of saving the value.
178 protected function _update_theme_mod( $value ) {
179 // Handle non-array theme mod.
180 if ( empty( $this->id_data[ 'keys' ] ) )
181 return set_theme_mod( $this->id_data[ 'base' ], $value );
183 // Handle array-based theme mod.
184 $mods = get_theme_mod( $this->id_data[ 'base' ] );
185 $mods = $this->multidimensional_replace( $mods, $this->id_data[ 'keys' ], $value );
186 if ( isset( $mods ) )
187 return set_theme_mod( $this->id_data[ 'base' ], $mods );
191 * Update the theme mod from the value of the parameter.
195 * @param $value mixed The value to update.
196 * @return mixed The result of saving the value.
198 protected function _update_option( $value ) {
199 // Handle non-array option.
200 if ( empty( $this->id_data[ 'keys' ] ) )
201 return update_option( $this->id_data[ 'base' ], $value );
203 // Handle array-based options.
204 $options = get_option( $this->id_data[ 'base' ] );
205 $options = $this->multidimensional_replace( $options, $this->id_data[ 'keys' ], $value );
206 if ( isset( $options ) )
207 return update_option( $this->id_data[ 'base' ], $options );
211 * Fetch the value of the parameter for a specific theme.
215 * @return mixed The requested value.
217 public function value() {
218 switch( $this->type ) {
220 $function = 'get_theme_mod';
223 $function = 'get_option';
226 return apply_filters( 'customize_value_' . $this->id_data[ 'base' ], $this->default );
229 // Handle non-array value
230 if ( empty( $this->id_data[ 'keys' ] ) )
231 return $function( $this->id_data[ 'base' ], $this->default );
233 // Handle array-based value
234 $values = $function( $this->id_data[ 'base' ] );
235 return $this->multidimensional_get( $values, $this->id_data[ 'keys' ], $this->default );
239 * Escape the parameter's value for use in JavaScript.
243 * @return mixed The requested escaped value.
245 public function js_value() {
246 $value = apply_filters( "customize_sanitize_js_{$this->id}", $this->value(), $this );
248 if ( is_string( $value ) )
249 return html_entity_decode( $value, ENT_QUOTES, 'UTF-8');
255 * Check if the theme supports the setting and check user capabilities.
259 * @return bool False if theme doesn't support the setting or user can't change setting, otherwise true.
261 public final function check_capabilities() {
262 if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) )
265 if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) )
272 * Multidimensional helper function.
278 * @param bool $create Default is false.
281 final protected function multidimensional( &$root, $keys, $create = false ) {
282 if ( $create && empty( $root ) )
285 if ( ! isset( $root ) || empty( $keys ) )
288 $last = array_pop( $keys );
291 foreach ( $keys as $key ) {
292 if ( $create && ! isset( $node[ $key ] ) )
293 $node[ $key ] = array();
295 if ( ! is_array( $node ) || ! isset( $node[ $key ] ) )
298 $node = &$node[ $key ];
301 if ( $create && ! isset( $node[ $last ] ) )
302 $node[ $last ] = array();
304 if ( ! isset( $node[ $last ] ) )
315 * Will attempt to replace a specific value in a multidimensional array.
321 * @param mixed $value The value to update.
324 final protected function multidimensional_replace( $root, $keys, $value ) {
325 if ( ! isset( $value ) )
327 elseif ( empty( $keys ) ) // If there are no keys, we're replacing the root.
330 $result = $this->multidimensional( $root, $keys, true );
332 if ( isset( $result ) )
333 $result['node'][ $result['key'] ] = $value;
339 * Will attempt to fetch a specific value from a multidimensional array.
345 * @param $default A default value which is used as a fallback. Default is null.
346 * @return mixed The requested value or the default value.
348 final protected function multidimensional_get( $root, $keys, $default = null ) {
349 if ( empty( $keys ) ) // If there are no keys, test the root.
350 return isset( $root ) ? $root : $default;
352 $result = $this->multidimensional( $root, $keys );
353 return isset( $result ) ? $result['node'][ $result['key'] ] : $default;
357 * Will attempt to check if a specific value in a multidimensional array is set.
363 * @return bool True if value is set, false if not.
365 final protected function multidimensional_isset( $root, $keys ) {
366 $result = $this->multidimensional_get( $root, $keys );
367 return isset( $result );
372 * A setting that is used to filter a value, but will not save the results.
374 * Results should be properly handled using another setting or callback.
376 class WP_Customize_Filter_Setting extends WP_Customize_Setting {
377 public function update() {}
381 * A setting that is used to filter a value, but will not save the results.
383 * Results should be properly handled using another setting or callback.
385 final class WP_Customize_Header_Image_Setting extends WP_Customize_Setting {
386 public $id = 'header_image_data';
388 public function update( $value ) {
389 global $custom_image_header;
391 // If the value doesn't exist (removed or random),
392 // use the header_image value.
394 $value = $this->manager->get_setting('header_image')->post_value();
396 if ( is_array( $value ) && isset( $value['choice'] ) )
397 $custom_image_header->set_header_image( $value['choice'] );
399 $custom_image_header->set_header_image( $value );
403 final class WP_Customize_Background_Image_Setting extends WP_Customize_Setting {
404 public $id = 'background_image_thumb';
406 public function update( $value ) {
407 remove_theme_mod( 'background_image_thumb' );