WP_Customize_Setting::preview(): bool

In this article

Add filters to supply the setting’s value when accessed.

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

bool False when preview short-circuits due no change needing to be previewed.

Source

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 $setting 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 $setting WP_Customize_Setting instance.
			 */
			do_action( "customize_preview_{$this->type}", $this );
	}

	$this->is_previewed = true;

	return true;
}

Hooks

do_action( “customize_preview_{$this->id}”, WP_Customize_Setting $setting )

Fires when the WP_Customize_Setting::preview() method is called for settings not handled as theme_mods or options.

do_action( “customize_preview_{$this->type}”, WP_Customize_Setting $setting )

Fires when the WP_Customize_Setting::preview() method is called for settings not handled as theme_mods or options.

Changelog

VersionDescription
4.4.0Added boolean return value.
3.4.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.