Class: WP_Customize_Widgets

Customize Widgets class.

Implements widget management in the Customizer.

Methods


Properties

Name Type(s) Default Value Summary
manager WP_Customize_Manager WP_Customize_Manager instance.
core_widget_id_bases array All id_bases for widgets defined in core.
rendered_sidebars array
rendered_widgets array
old_sidebars_widgets array
selective_refreshable_widgets array Mapping of widget ID base to whether it supports selective refresh.
setting_id_patterns array Mapping of setting type to setting ID pattern.
before_widget_tags_seen array List of the tag names seen for before_widget strings.

This is used in the \'filter_wp_kses_allowed_html' filter to ensure that the data-* attributes can be whitelisted.

sidebar_instance_count array Keep track of the number of times that dynamic_sidebar() was called for a given sidebar index.

This helps facilitate the uncommon scenario where a single sidebar is rendered multiple times on a template.

context_sidebar_instance_number integer The current request's sidebar_instance_number context.
current_dynamic_sidebar_id_stack array Current sidebar ID being rendered.
rendering_widget_id string Current sidebar being rendered.
rendering_sidebar_id string Current widget being rendered.
_captured_options array List of captured widget option updates.
_is_capturing_option_updates boolean Whether option capture is currently happening.

Methods

WP_Customize_Widgets:: __construct( WP_Customize_Manager $manager )

Initial loader. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$manager WP_Customize_Manager

Customize manager bootstrap instance.


WP_Customize_Widgets:: _sort_name_callback( array $widget_a, array $widget_b )

Naturally orders available widgets by name. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$widget_a array

The first widget to compare.

$widget_b array

The second widget to compare.

Returns

integer

Reorder position for the current widget comparison.


WP_Customize_Widgets:: call_widget_update( string $widget_id )

Finds and invokes the widget update and control callbacks. Since 3.9.0.

Requires that $_POST be populated with the instance data.

Arguments

Name Type(s) Default Value Description
$widget_id string

Widget ID.

Returns

WP_Error | array

Array containing the updated widget information. A WP_Error object, otherwise.


WP_Customize_Widgets:: capture_filter_pre_get_option( mixed $value )

Pre-filters captured option values before retrieving. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$value mixed

Value to return instead of the option value.

Returns

mixed

Filtered option value.


WP_Customize_Widgets:: capture_filter_pre_update_option( mixed $new_value, string $option_name, mixed $old_value )

Pre-filters captured option values before updating. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$new_value mixed

The new option value.

$option_name string

Name of the option.

$old_value mixed

The old option value.

Returns

mixed

Filtered option value.


WP_Customize_Widgets:: count_captured_options( )

Retrieves the number of captured widget option updates. Since 3.9.0.

Returns

integer

Number of updated options.


WP_Customize_Widgets:: customize_controls_init( )

Ensures all widgets get loaded into the Customizer. Since 3.9.0.

Note: these actions are also fired in wp_ajax_update_widget().


WP_Customize_Widgets:: customize_dynamic_partial_args( array | false $partial_args, string $partial_id )

Filters arguments for dynamic widget partials. Since 4.5.0.

Arguments

Name Type(s) Default Value Description
$partial_args array | false

Partial arguments.

$partial_id string

Partial ID.

Returns

array

(Maybe) modified partial arguments.


WP_Customize_Widgets:: customize_preview_enqueue( )

Enqueues scripts for the Customizer preview. Since 3.9.0.


WP_Customize_Widgets:: customize_preview_init( )

Adds hooks for the Customizer preview. Since 3.9.0.


WP_Customize_Widgets:: customize_register( )

Registers Customizer settings and controls for all sidebars and widgets. Since 3.9.0.


WP_Customize_Widgets:: end_dynamic_sidebar( integer | string $index )

Finishes keeping track of the current sidebar being rendered. Since 4.5.0.

Inserts a marker after widgets are rendered in a dynamic sidebar.

Arguments

Name Type(s) Default Value Description
$index integer | string

Index, name, or ID of the dynamic sidebar.


WP_Customize_Widgets:: enqueue_scripts( )

Enqueues scripts and styles for Customizer panel and export data to JavaScript. Since 3.9.0.


WP_Customize_Widgets:: export_preview_data( )

Communicates the sidebars that appeared on the page at the very end of the page, and at the very end of the wp_footer, Since 3.9.0.


WP_Customize_Widgets:: filter_customize_dynamic_setting_args( false | array $args, string $setting_id )

Determines the arguments for a dynamically-created setting. Since 4.2.0.

Arguments

Name Type(s) Default Value Description
$args false | array

The arguments to the WP_Customize_Setting constructor.

$setting_id string

ID for dynamic setting, usually coming from $_POST['customized'].

Returns

false | array

Setting arguments, false otherwise.


WP_Customize_Widgets:: filter_customize_value_old_sidebars_widgets_data( array $old_sidebars_widgets )

Filters old_sidebars_widgets_data Customizer setting. Since 3.9.0.

When switching themes, filter the Customizer setting old_sidebars_widgets_data to supply initial $sidebars_widgets before they were overridden by retrieve_widgets(). The value for old_sidebars_widgets_data gets set in the old theme's sidebars_widgets theme_mod.

Arguments

Name Type(s) Default Value Description
$old_sidebars_widgets array

Returns

array


WP_Customize_Widgets:: filter_dynamic_sidebar_params( array $params )

Inject selective refresh data attributes into widget container elements. Since 4.5.0.

Arguments

Name Type(s) Default Value Description
$params array

{ Dynamic sidebar params.

@type array $args        Sidebar args.
@type array $widget_args Widget args.

}

Returns

array

Params.


WP_Customize_Widgets:: filter_option_sidebars_widgets_for_theme_switch( array $sidebars_widgets )

Filters sidebars_widgets option for theme switch. Since 3.9.0.

When switching themes, the retrieve_widgets() function is run when the Customizer initializes, and then the new sidebars_widgets here get supplied as the default value for the sidebars_widgets option.

Arguments

Name Type(s) Default Value Description
$sidebars_widgets array

Returns

array


WP_Customize_Widgets:: filter_sidebars_widgets_for_rendering_widget( array $sidebars_widgets )

Filters sidebars_widgets to ensure the currently-rendered widget is the only widget in the current sidebar. Since 4.5.0.

Arguments

Name Type(s) Default Value Description
$sidebars_widgets array

Sidebars widgets.

Returns

array

Filtered sidebars widgets.


WP_Customize_Widgets:: filter_wp_kses_allowed_data_attributes( array $allowed_html )

Ensures the HTML data-* attributes for selective refresh are allowed by kses. Since 4.5.0.

This is needed in case the $before_widget is run through wp_kses() when printed.

Arguments

Name Type(s) Default Value Description
$allowed_html array

Allowed HTML.

Returns

array

(Maybe) modified allowed HTML.


WP_Customize_Widgets:: get_available_widgets( )

Builds up an index of all available widgets for use in Backbone models. Since 3.9.0.

Returns

array

List of available widgets.


WP_Customize_Widgets:: get_captured_option( string $option_name, mixed $default = false )

Retrieves the option that was captured from being saved. Since 4.2.0.

Arguments

Name Type(s) Default Value Description
$option_name string

Option name.

$default mixed

Optional. Default value to return if the option does not exist. Default false.

Returns

mixed

Value set for the option.


WP_Customize_Widgets:: get_captured_options( )

Retrieves captured widget option updates. Since 3.9.0.

Returns

array

Array of captured options.


WP_Customize_Widgets:: get_instance_hash_key( string $serialized_instance )

Retrieves MAC for a serialized widget instance string. Since 3.9.0.

Allows values posted back from JS to be rejected if any tampering of the data has occurred.

Arguments

Name Type(s) Default Value Description
$serialized_instance string

Widget instance.

Returns

string

MAC for serialized widget instance.


WP_Customize_Widgets:: get_post_value( string $name, mixed $default = null )

Retrieves an unslashed post value or return a default. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$name string

Post value.

$default mixed

Default post value.

Returns

mixed

Unslashed post value or default value.


WP_Customize_Widgets:: get_selective_refreshable_widgets( )

List whether each registered widget can be use selective refresh. Since 4.5.0.

If the theme does not support the customize-selective-refresh-widgets feature, then this will always return an empty array.

Returns

array

Mapping of id_base to support. If theme doesn't support selective refresh, an empty array is returned.


WP_Customize_Widgets:: get_setting_args( string $id, array $overrides = array() )

Retrieves common arguments to supply when constructing a Customizer setting. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$id string

Widget setting ID.

$overrides array

Array of setting overrides.

Returns

array

Possibly modified setting arguments.


WP_Customize_Widgets:: get_setting_id( string $widget_id )

Converts a widget_id into its corresponding Customizer setting ID (option name). Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$widget_id string

Widget ID.

Returns

string

Maybe-parsed widget ID.


WP_Customize_Widgets:: get_setting_type( string $setting_id )

Retrieves the widget setting type given a setting ID. Since 4.2.0.

Arguments

Name Type(s) Default Value Description
$setting_id string

Setting ID.

Returns

string | void

Setting type.


WP_Customize_Widgets:: get_widget_control( array $args )

Retrieves the widget control markup. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$args array

Widget control arguments.

Returns

string

Widget control form HTML markup.


WP_Customize_Widgets:: get_widget_control_parts( array $args )

Retrieves the widget control markup parts. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$args array

Widget control arguments.

Returns

array

{ @type string $control Markup for widget control wrapping form. @type string $content The contents of the widget form itself. }


WP_Customize_Widgets:: is_option_capture_ignored( string $option_name )

Determines whether the captured option update should be ignored. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$option_name string

Option name.

Returns

boolean

Whether the option capture is ignored.


WP_Customize_Widgets:: is_panel_active( )

Determines whether the widgets panel is active, based on whether there are sidebars registered. Since 4.4.0.

Returns

boolean

Active.


WP_Customize_Widgets:: is_sidebar_rendered( string $sidebar_id )

Determines if a sidebar is rendered on the page. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$sidebar_id string

Sidebar ID to check.

Returns

boolean

Whether the sidebar is rendered.


WP_Customize_Widgets:: is_wide_widget( string $widget_id )

Determines whether the widget is considered "wide". Since 3.9.0.

Core widgets which may have controls wider than 250, but can still be shown in the narrow Customizer panel. The RSS and Text widgets in Core, for example, have widths of 400 and yet they still render fine in the Customizer panel.

This method will return all Core widgets as being not wide, but this can be overridden with the \'is_wide_widget_in_customizer' filter.

Arguments

Name Type(s) Default Value Description
$widget_id string

Widget ID.

Returns

boolean

Whether or not the widget is a "wide" widget.


WP_Customize_Widgets:: is_widget_rendered( string $widget_id )

Determine if a widget is rendered on the page. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$widget_id string

Widget ID to check.

Returns

boolean

Whether the widget is rendered.


WP_Customize_Widgets:: is_widget_selective_refreshable( string $id_base )

Determines if a widget supports selective refresh. Since 4.5.0.

Arguments

Name Type(s) Default Value Description
$id_base string

Widget ID Base.

Returns

boolean

Whether the widget can be selective refreshed.


WP_Customize_Widgets:: output_widget_control_templates( )

Renders the widget form control templates into the DOM. Since 3.9.0.


WP_Customize_Widgets:: override_sidebars_widgets_for_theme_switch( )

Override sidebars_widgets for theme switch. Since 3.9.0.

When switching a theme via the Customizer, supply any previously-configured sidebars_widgets from the target theme as the initial sidebars_widgets setting. Also store the old theme's existing settings so that they can be passed along for storing in the sidebars_widgets theme_mod when the theme gets switched.


WP_Customize_Widgets:: parse_widget_id( string $widget_id )

Converts a widget ID into its id_base and number components. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$widget_id string

Widget ID.

Returns

array

Array containing a widget's id_base and number components.


WP_Customize_Widgets:: parse_widget_setting_id( string $setting_id )

Converts a widget setting ID (option path) to its id_base and number components. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$setting_id string

Widget setting ID.

Returns

WP_Error | array

Array containing a widget's id_base and number components, or a WP_Error object.


WP_Customize_Widgets:: prepreview_added_sidebars_widgets( )

This method is deprecated.

{@internal Missing Summary} Since 3.9.0.

See the \'customize_dynamic_setting_args' filter.


WP_Customize_Widgets:: prepreview_added_widget_instance( )

This method is deprecated.

{@internal Missing Summary} Since 3.9.0.

See the \'customize_dynamic_setting_args' filter.


WP_Customize_Widgets:: preview_sidebars_widgets( array $sidebars_widgets )

When previewing, ensures the proper previewing widgets are used. Since 3.9.0.

Because wp_get_sidebars_widgets() gets called early at \'init' (via wp_convert_widget_settings()) and can set global variable $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' ) before the Customizer preview filter is added, it has to be reset after the filter has been added.

Arguments

Name Type(s) Default Value Description
$sidebars_widgets array

List of widgets for the current sidebar.

Returns

array


Calls admin_print_footer_scripts and admin_print_scripts hooks to allow custom scripts from plugins. Since 3.9.0.


WP_Customize_Widgets:: print_preview_css( )

Inserts default style for highlighted widget at early point so theme stylesheet can override. Since 3.9.0.


WP_Customize_Widgets:: print_scripts( )

Calls admin_print_scripts-widgets.php and admin_print_scripts hooks to allow custom scripts from plugins. Since 3.9.0.


WP_Customize_Widgets:: print_styles( )

Calls admin_print_styles-widgets.php and admin_print_styles hooks to allow custom styles from plugins. Since 3.9.0.


WP_Customize_Widgets:: refresh_nonces( array $nonces )

Refreshes the nonce for widget updates. Since 4.2.0.

Arguments

Name Type(s) Default Value Description
$nonces array

Array of nonces.

Returns

array

$nonces Array of nonces.


WP_Customize_Widgets:: register_settings( )

Inspects the incoming customized data for any widget settings, and dynamically adds them up-front so widgets will be initialized properly. Since 4.2.0.


WP_Customize_Widgets:: remove_prepreview_filters( )

This method is deprecated.

{@internal Missing Summary} Since 3.9.0.

See the \'customize_dynamic_setting_args' filter.


WP_Customize_Widgets:: render_widget_partial( WP_Customize_Partial $partial, array $context )

Renders a specific widget using the supplied sidebar arguments. Since 4.5.0.

Arguments

Name Type(s) Default Value Description
$partial WP_Customize_Partial

Partial.

$context array

{ Sidebar args supplied as container context.

@type string $sidebar_id              ID for sidebar for widget to render into.
@type int    $sidebar_instance_number Disambiguating instance number.

}

Returns

string | false


WP_Customize_Widgets:: sanitize_sidebar_widgets( array<mixed,string> $widget_ids )

Ensures sidebar widget arrays only ever contain widget IDS. Since 3.9.0.

Used as the 'sanitize_callback' for each $sidebars_widgets setting.

Arguments

Name Type(s) Default Value Description
$widget_ids array<mixed,string>

Array of widget IDs.

Returns

array<mixed,string>

Array of sanitized widget IDs.


WP_Customize_Widgets:: sanitize_sidebar_widgets_js_instance( array $widget_ids )

Strips out widget IDs for widgets which are no longer registered. Since 3.9.0.

One example where this might happen is when a plugin orphans a widget in a sidebar upon deactivation.

Arguments

Name Type(s) Default Value Description
$widget_ids array

List of widget IDs.

Returns

array

Parsed list of widget IDs.


WP_Customize_Widgets:: sanitize_widget_instance( array $value )

Sanitizes a widget instance. Since 3.9.0.

Unserialize the JS-instance for storing in the options. It's important that this filter only get applied to an instance once.

Arguments

Name Type(s) Default Value Description
$value array

Widget instance to sanitize.

Returns

array | void

Sanitized widget instance.


WP_Customize_Widgets:: sanitize_widget_js_instance( array $value )

Converts a widget instance into JSON-representable format. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$value array

Widget instance to convert to JSON.

Returns

array

JSON-converted widget instance.


WP_Customize_Widgets:: schedule_customize_register( )

Ensures widgets are available for all types of previews. Since 3.9.0.

When in preview, hook to \'customize_register' for settings after WordPress is loaded so that all filters have been initialized (e.g. Widget Visibility).


WP_Customize_Widgets:: selective_refresh_init( )

Adds hooks for selective refresh. Since 4.5.0.


WP_Customize_Widgets:: setup_widget_addition_previews( )

This method is deprecated.

{@internal Missing Summary} Since 3.9.0.

See the \'customize_dynamic_setting_args' filter.


WP_Customize_Widgets:: start_capturing_option_updates( )

Begins keeping track of changes to widget options, caching new values. Since 3.9.0.


WP_Customize_Widgets:: start_dynamic_sidebar( integer | string $index )

Begins keeping track of the current sidebar being rendered. Since 4.5.0.

Insert marker before widgets are rendered in a dynamic sidebar.

Arguments

Name Type(s) Default Value Description
$index integer | string

Index, name, or ID of the dynamic sidebar.


WP_Customize_Widgets:: stop_capturing_option_updates( )

Undoes any changes to the options since options capture began. Since 3.9.0.


WP_Customize_Widgets:: tally_rendered_widgets( array $widget )

Tracks the widgets that were rendered. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$widget array

Rendered widget to tally.


WP_Customize_Widgets:: tally_sidebars_via_dynamic_sidebar_calls( boolean $has_widgets, string $sidebar_id )

Tallies the sidebars rendered via dynamic_sidebar(). Since 3.9.0.

Keep track of the times that dynamic_sidebar() is called in the template, and assume this means the sidebar would be rendered on the template if there were widgets populating it.

Arguments

Name Type(s) Default Value Description
$has_widgets boolean

Whether the current sidebar has widgets.

$sidebar_id string

Sidebar ID.

Returns

boolean

Whether the current sidebar has widgets.


WP_Customize_Widgets:: tally_sidebars_via_is_active_sidebar_calls( boolean $is_active, string $sidebar_id )

Tallies the sidebars rendered via is_active_sidebar(). Since 3.9.0.

Keep track of the times that is_active_sidebar() is called in the template, and assume that this means that the sidebar would be rendered on the template if there were widgets populating it.

Arguments

Name Type(s) Default Value Description
$is_active boolean

Whether the sidebar is active.

$sidebar_id string

Sidebar ID.

Returns

boolean

Whether the sidebar is active.


WP_Customize_Widgets:: wp_ajax_update_widget( )

Updates widget settings asynchronously. Since 3.9.0.

Allows the Customizer to update a widget using its form, but return the new instance info via Ajax instead of saving it to the options table.

Most code here copied from wp_ajax_save_widget().


WordPress Developer Newsletter

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