wpdevtools.io Logo

Class: WP_Customize_Background_Image_Setting

Extends WP_Customize_Setting

Customizer Background Image Setting class.

Handles saving and sanitizing of settings.

Properties

Methods

Properties

Name Type(s) Default Value Summary
id string Inherited ⋅ Unique string identifier for the setting.
manager WP_Customize_Manager Inherited ⋅ Customizer bootstrap instance.
type string Inherited ⋅ Type of customize settings.
capability string | array Inherited ⋅ Capability required to edit this setting.
theme_supports string Inherited ⋅ Feature a theme is required to support to enable this setting.
default string Inherited ⋅ The default value for the setting.
transport string Inherited ⋅ Options for rendering the live preview of changes in Theme Customizer.

Set this value to 'postMessage' to enable a custom Javascript handler to render changes to this setting as opposed to reloading the whole page.
validate_callback callable Inherited ⋅ Server-side validation callback for the setting's value.
sanitize_callback callable Inherited ⋅ Callback to filter a Customize setting value in un-slashed form.
sanitize_js_callback string Inherited ⋅ Callback to convert a Customize PHP setting value to a value that is JSON serializable.
dirty boolean Inherited ⋅ Whether or not the setting is initially dirty when created.

This is used to ensure that a setting will be sent from the pane to the preview when loading the Customizer. Normally a setting only is synced to the preview if it has been changed. This allows the setting to be sent from the start.
id_data array Inherited ⋅ ID Data.
is_previewed boolean Inherited ⋅ Whether or not preview() was called.
aggregated_multidimensionals array Inherited ⋅ Static ⋅ Cache of multidimensional values to improve performance.
is_multidimensional_aggregated boolean Inherited ⋅ Whether the multidimensional setting is aggregated.
_previewed_blog_id integer Inherited ⋅ The ID for the current site when the preview() method was called.
_original_value mixed Inherited ⋅ Original non-previewed value stored by the preview method.

Methods

WP_Customize_Background_Image_Setting:: __construct( WP_Customize_Manager $manager, string $id, array $args = array() )

Constructor. Since 3.4.0.

Any supplied $args override class property defaults.

Arguments

Name Type(s) Default Value Description
$manager WP_Customize_Manager
$id string

An specific ID of the setting. Can be a theme mod or option name.
$args array

Setting arguments.

WP_Customize_Background_Image_Setting:: _clear_aggregated_multidimensional_preview_applied_flag( )

Clear out the previewed-applied flag for a multidimensional-aggregated value whenever its post value is updated. Since 4.4.0.

This ensures that the new value will get sanitized and used the next time that WP_Customize_Setting::_multidimensional_preview_filter() is called for this setting.

WP_Customize_Background_Image_Setting:: _multidimensional_preview_filter( mixed $original )

Callback function to filter multidimensional theme mods and options. Since 4.4.0.

For all multidimensional settings of a given type, the preview filter for the first setting previewed will be used to apply the values for the others.

Arguments

Name Type(s) Default Value Description
$original mixed

Original root value.

Returns

mixed

New or old value.

WP_Customize_Background_Image_Setting:: _preview_filter( mixed $original )

Callback function to filter non-multidimensional theme mods and options. Since 3.4.0.

If switch_to_blog() was called after the preview() method, and the current site is now not the same site, then this method does a no-op and returns the original value.

Arguments

Name Type(s) Default Value Description
$original mixed

Old value.

Returns

mixed

New or old value.

WP_Customize_Background_Image_Setting:: _update_option( )

This method is deprecated.

Deprecated method. Since 3.4.0.

WP_Customize_Background_Image_Setting:: _update_theme_mod( )

This method is deprecated.

Deprecated method. Since 3.4.0.

WP_Customize_Background_Image_Setting:: aggregate_multidimensional( )

Set up the setting for aggregated multidimensional values. Since 4.4.0.

When a multidimensional setting gets aggregated, all of its preview and update calls get combined into one call, greatly improving performance.

WP_Customize_Background_Image_Setting:: check_capabilities( )

Validate user capabilities whether the theme supports the setting. Since 3.4.0.

Returns

boolean

False if theme doesn't support the setting or user can't change setting, otherwise true.

WP_Customize_Background_Image_Setting:: get_root_value( mixed $default = null )

Get the root value for a setting, especially for multidimensional ones. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$default mixed

Value to return if root does not exist.

Returns

mixed

WP_Customize_Background_Image_Setting:: id_data( )

Get parsed ID data for multidimensional setting. Since 4.4.0.

Returns

array

{ ID data for multidimensional setting.

@type string $base ID base
@type array  $keys Keys for multidimensional array.

}

WP_Customize_Background_Image_Setting:: is_current_blog_previewed( )

Return true if the current site is not the same as the previewed site. Since 4.2.0.

Returns

boolean

If preview() has been called.

WP_Customize_Background_Image_Setting:: js_value( )

Sanitize the setting's value for use in JavaScript. Since 3.4.0.

Returns

mixed

The requested escaped value.

WP_Customize_Background_Image_Setting:: json( )

Retrieves the data to export to the client via JSON. Since 4.6.0.

Returns

array

Array of parameters passed to JavaScript.

WP_Customize_Background_Image_Setting:: multidimensional( &$root, $keys, boolean $create = false )

Multidimensional helper function. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys
$create boolean

Default is false.

Returns

array | void

Keys are 'root', 'node', and 'key'.

WP_Customize_Background_Image_Setting:: multidimensional_get( $root, $keys, mixed $default = null )

Will attempt to fetch a specific value from a multidimensional array. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys
$default mixed

A default value which is used as a fallback. Default is null.

Returns

mixed

The requested value or the default value.

WP_Customize_Background_Image_Setting:: multidimensional_isset( $root, $keys )

Will attempt to check if a specific value in a multidimensional array is set. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys

Returns

boolean

True if value is set, false if not.

WP_Customize_Background_Image_Setting:: multidimensional_replace( $root, $keys, mixed $value )

Will attempt to replace a specific value in a multidimensional array. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys
$value mixed

The value to update.

Returns

mixed

WP_Customize_Background_Image_Setting:: post_value( mixed $default = null )

Fetch and sanitize the $_POST value for the setting. Since 3.4.0.

During a save request prior to save, post_value() provides the new value while value() does not.

Arguments

Name Type(s) Default Value Description
$default mixed

A default value which is used as a fallback. Default is null.

Returns

mixed

The default value on failure, otherwise the sanitized and validated value.

WP_Customize_Background_Image_Setting:: preview( )

Add filters to supply the setting's value when accessed. Since 3.4.0. Since 4.4.0.

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.

Returns

boolean

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

WP_Customize_Background_Image_Setting:: sanitize( string | array $value )

Sanitize an input. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$value string | array

The value to sanitize.

Returns

string | array | null | WP_Error

Sanitized value, or null/WP_Error if invalid.

WP_Customize_Background_Image_Setting:: save( )

Checks user capabilities and theme supports, and then saves the value of the setting. Since 3.4.0.

Returns

false | void

False if cap check fails or value isn't set or is invalid.

WP_Customize_Background_Image_Setting:: set_root_value( mixed $value )

Set the root value for a setting, especially for multidimensional ones. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$value mixed

Value to set as root of multidimensional setting.

Returns

boolean

Whether the multidimensional root was updated successfully.

WP_Customize_Background_Image_Setting:: update( mixed $value )

Save the value of the setting, using the related API. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$value mixed

The value to update.

Returns

boolean

The result of saving the value.

WP_Customize_Background_Image_Setting:: validate( mixed $value )

Validates an input. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$value mixed

Value to validate.

Returns

true | WP_Error

True if the input was validated, otherwise WP_Error.

WP_Customize_Background_Image_Setting:: value( )

Fetch the value of the setting. Since 3.4.0.

Returns

mixed

The value.

WordPress Developer Newsletter

Stay informed of new chapter releases, important WordPress API updates and more.