WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Class Reference/WP Customize Widgets

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

See also index of Class Reference and index of Function Reference.