WP_Customize_Setting::preview PHP Method

preview() public method

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.
Since: 3.4.0
Since: 4.4.0 Added boolean return value.
public preview ( ) : boolean
return boolean False when preview short-circuits due no change needing to be previewed.
    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;
    }

Usage Example

Exemplo n.º 1
0
	/**
	 * Test specific fix for setting's default value not applying on preview window
	 *
	 * @ticket 30988
	 */
	function test_non_posted_setting_applying_default_value_in_preview() {
		$type = 'option';
		$name = 'unset_option_without_post_value';
		$default = "default_value_{$name}";
		$setting = new WP_Customize_Setting( $this->manager, $name, compact( 'type', 'default' ) );
		$this->assertEquals( $this->undefined, get_option( $name, $this->undefined ) );
		$this->assertEquals( $default, $setting->value() );
		$setting->preview();
		$this->assertEquals( $default, get_option( $name, $this->undefined ), sprintf( 'Expected get_option(%s) to return setting default: %s.', $name, $default ) );
		$this->assertEquals( $default, $setting->value() );
	}
All Usage Examples Of WP_Customize_Setting::preview