WordPress.org

Role of WP_Customize_Widgets

WP_Customize_Widgets is WordPress' class for implementing widget management via the Theme Customization API for WordPress 3.9 and newer.

This live preview and management of widgets via the Customizer serves as a secondary option to the traditional widget management workflow already in place.

Usage

WordPress instantiates the class via WP_Customize_Manager and works by adding a new Customizer section for each of the active sidebars visible in the Customizer preview.

Methods and Properties

Properties

$manager

WP_Customize_Manager instance.

$core_widget_id_bases

(array) All id_bases for widgets defined in core.

Methods

get_post_value( $name, $default = null )

Get an unslashed post value or return a default.

setup_widget_addition_previews()

Set up widget addition previews.

Since the widgets get registered on 'widgets_init' before the Customizer settings are set up on 'customize_register', we have to filter the options similarly to how the setting previewer will filter the options later.

prepreview_added_sidebars_widgets( $sidebars_widgets )

Ensure that newly-added widgets will appear in the widgets_sidebars.

prepreview_added_widget_instance( $value = false )

Ensure newly-added widgets have empty instances so they will be recognized.

remove_prepreview_filters()

Remove pre-preview filters.

override_sidebars_widgets_for_theme_switch()

Override sidebars_widgets for theme switch.

filter_customize_value_old_sidebars_widgets_data( $old_sidebars_widgets )

Filter old_sidebars_widgets_data customizer setting.

filter_option_sidebars_widgets_for_theme_switch( $sidebars_widgets )

Filter sidebars_widgets option for theme switch.

customize_controls_init

Make sure all widgets get loaded into the Customizer.

schedule_customize_register()

Ensure widgets are available for all types of previews.

customize_register()

Register customizer settings and controls for all sidebars and widgets.

get_setting_id( $widget_id )

Convert a widget_id into its corresponding customizer setting ID (option name).

is_wide_widget( $widget_id )

Determine whether the widget is considered "wide".

parse_widget_id( $widget_id )

Convert a widget ID into its id_base and number components.

parse_widget_setting_id( $setting_id )

Convert a widget setting ID (option path) to its id_base and number components.

print_styles()

Print styles.

print_scripts()

Print scripts.

enqueue_scripts

Enqueue scripts.

output_widget_control_templates()

Render the widget form control templates into the DOM.

print_footer_scripts()

Print footer scripts.

get_setting_args( $id, $overrides = array() )

Get common arguments to supply when constructing a Customizer setting.

sanitize_sidebar_widgets( $widget_ids )

Make sure that sidebar widget arrays only ever contain widget IDS. Used as the 'sanitize_callback' for each $sidebars_widgets setting.

get_available_widgets()

Build up an index of all available widgets for use in Backbone models.

get_widget_control( $args )

Get the widget control markup.

customize_preview_init()

Add hooks for the customizer preview.

preview_sidebars_widgets( $sidebars_widgets )

When previewing, make sure the proper previewing widgets are used.

customize_preview_enqueue()

Enqueue scripts for the Customizer preview.

print_preview_css

Insert default style for highlighted widget at early point so theme stylesheet can override.

export_preview_data()

At the very end of the page, at the very end of the wp_footer, communicate the sidebars that appeared on the page.

tally_rendered_widgets( $widget )

Keep track of the widgets that were rendered.

tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id )

Tally the sidebars rendered via is_active_sidebar().

tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id )

Tally the sidebars rendered via dynamic_sidebar().

sanitize_widget_instance( $value )

Sanitize a widget instance.

sanitize_widget_js_instance( $value )

Convert widget instance into JSON-representable format.

sanitize_sidebar_widgets_js_instance( $widget_ids )

Strip out widget IDs for widgets which are no longer registered.

call_widget_update( $widget_id )

Find and invoke the widget update and control callbacks.

wp_ajax_update_widget()

Update widget settings asynchronously.

capture_filter_pre_update_option( $new_value, $option_name, $old_value )

Pre-filter captured option values before updating.

capture_filter_pre_get_option( $value )

Pre-filter captured option values before retrieving.

Hooks

• customizer_widgets_section_args
• is_wide_widget_in_customizer
• widget_customizer_setting_args

Source File

WP_Customize_Widgets is located in wp-includes/class-wp-customize-widgets.php.

Related