WP_Customize_Setting::preview()
Add filters to supply the setting’s value when accessed.
Description Description
If the setting already has a pre-existing value and there is no incoming post value for the setting, then this method will short-circuit since there is no change to preview.
Return Return
(bool) False when preview short-circuits due no change needing to be previewed.
Source Source
File: wp-includes/class-wp-customize-setting.php
public function preview() { if ( ! isset( $this->_previewed_blog_id ) ) { $this->_previewed_blog_id = get_current_blog_id(); } // Prevent re-previewing an already-previewed setting. if ( $this->is_previewed ) { return true; } $id_base = $this->id_data['base']; $is_multidimensional = ! empty( $this->id_data['keys'] ); $multidimensional_filter = array( $this, '_multidimensional_preview_filter' ); /* * Check if the setting has a pre-existing value (an isset check), * and if doesn't have any incoming post value. If both checks are true, * then the preview short-circuits because there is nothing that needs * to be previewed. */ $undefined = new stdClass(); $needs_preview = ( $undefined !== $this->post_value( $undefined ) ); $value = null; // Since no post value was defined, check if we have an initial value set. if ( ! $needs_preview ) { if ( $this->is_multidimensional_aggregated ) { $root = self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value']; $value = $this->multidimensional_get( $root, $this->id_data['keys'], $undefined ); } else { $default = $this->default; $this->default = $undefined; // Temporarily set default to undefined so we can detect if existing value is set. $value = $this->value(); $this->default = $default; } $needs_preview = ( $undefined === $value ); // Because the default needs to be supplied. } // If the setting does not need previewing now, defer to when it has a value to preview. if ( ! $needs_preview ) { if ( ! has_action( "customize_post_value_set_{$this->id}", array( $this, 'preview' ) ) ) { add_action( "customize_post_value_set_{$this->id}", array( $this, 'preview' ) ); } return false; } switch ( $this->type ) { case 'theme_mod': if ( ! $is_multidimensional ) { add_filter( "theme_mod_{$id_base}", array( $this, '_preview_filter' ) ); } else { if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) { // Only add this filter once for this ID base. add_filter( "theme_mod_{$id_base}", $multidimensional_filter ); } self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'][ $this->id ] = $this; } break; case 'option': if ( ! $is_multidimensional ) { add_filter( "pre_option_{$id_base}", array( $this, '_preview_filter' ) ); } else { if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) { // Only add these filters once for this ID base. add_filter( "option_{$id_base}", $multidimensional_filter ); add_filter( "default_option_{$id_base}", $multidimensional_filter ); } self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'][ $this->id ] = $this; } break; default: /** * Fires when the WP_Customize_Setting::preview() method is called for settings * not handled as theme_mods or options. * * The dynamic portion of the hook name, `$this->id`, refers to the setting ID. * * @since 3.4.0 * * @param WP_Customize_Setting $this WP_Customize_Setting instance. */ do_action( "customize_preview_{$this->id}", $this ); /** * Fires when the WP_Customize_Setting::preview() method is called for settings * not handled as theme_mods or options. * * The dynamic portion of the hook name, `$this->type`, refers to the setting type. * * @since 4.1.0 * * @param WP_Customize_Setting $this WP_Customize_Setting instance. */ do_action( "customize_preview_{$this->type}", $this ); } $this->is_previewed = true; return true; }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
4.4.0 | Added boolean return value. |
3.4.0 | Introduced. |