3
* Customize Widgets Class
5
* Implements widget management in the Customizer.
8
* @subpackage Customize
11
final class WP_Customize_Widgets {
14
* WP_Customize_Manager instance.
18
* @var WP_Customize_Manager
23
* All id_bases for widgets defined in core.
29
protected $core_widget_id_bases = array(
30
'archives', 'calendar', 'categories', 'links', 'meta',
31
'nav_menu', 'pages', 'recent-comments', 'recent-posts',
32
'rss', 'search', 'tag_cloud', 'text',
40
protected $_customized;
47
protected $_prepreview_added_filters = array();
54
protected $rendered_sidebars = array();
61
protected $rendered_widgets = array();
68
protected $old_sidebars_widgets = array();
76
* @param WP_Customize_Manager $manager Customize manager bootstrap instance.
78
public function __construct( $manager ) {
79
$this->manager = $manager;
81
add_action( 'after_setup_theme', array( $this, 'setup_widget_addition_previews' ) );
82
add_action( 'wp_loaded', array( $this, 'override_sidebars_widgets_for_theme_switch' ) );
83
add_action( 'customize_controls_init', array( $this, 'customize_controls_init' ) );
84
add_action( 'customize_register', array( $this, 'schedule_customize_register' ), 1 );
85
add_action( 'customize_controls_enqueue_scripts', array( $this, 'enqueue_scripts' ) );
86
add_action( 'customize_controls_print_styles', array( $this, 'print_styles' ) );
87
add_action( 'customize_controls_print_scripts', array( $this, 'print_scripts' ) );
88
add_action( 'customize_controls_print_footer_scripts', array( $this, 'print_footer_scripts' ) );
89
add_action( 'customize_controls_print_footer_scripts', array( $this, 'output_widget_control_templates' ) );
90
add_action( 'customize_preview_init', array( $this, 'customize_preview_init' ) );
92
add_action( 'dynamic_sidebar', array( $this, 'tally_rendered_widgets' ) );
93
add_filter( 'is_active_sidebar', array( $this, 'tally_sidebars_via_is_active_sidebar_calls' ), 10, 2 );
94
add_filter( 'dynamic_sidebar_has_widgets', array( $this, 'tally_sidebars_via_dynamic_sidebar_calls' ), 10, 2 );
98
* Get an unslashed post value or return a default.
104
* @param string $name Post value.
105
* @param mixed $default Default post value.
106
* @return mixed Unslashed post value or default value.
108
protected function get_post_value( $name, $default = null ) {
109
if ( ! isset( $_POST[ $name ] ) ) {
113
return wp_unslash( $_POST[$name] );
117
* Set up widget addition previews.
119
* Since the widgets get registered on 'widgets_init' before the customizer
120
* settings are set up on 'customize_register', we have to filter the options
121
* similarly to how the setting previewer will filter the options later.
127
public function setup_widget_addition_previews() {
128
$is_customize_preview = false;
130
if ( ! empty( $this->manager ) && ! is_admin() && 'on' === $this->get_post_value( 'wp_customize' ) ) {
131
$is_customize_preview = check_ajax_referer( 'preview-customize_' . $this->manager->get_stylesheet(), 'nonce', false );
134
$is_ajax_widget_update = false;
135
if ( $this->manager->doing_ajax() && 'update-widget' === $this->get_post_value( 'action' ) ) {
136
$is_ajax_widget_update = check_ajax_referer( 'update-widget', 'nonce', false );
139
$is_ajax_customize_save = false;
140
if ( $this->manager->doing_ajax() && 'customize_save' === $this->get_post_value( 'action' ) ) {
141
$is_ajax_customize_save = check_ajax_referer( 'save-customize_' . $this->manager->get_stylesheet(), 'nonce', false );
144
$is_valid_request = ( $is_ajax_widget_update || $is_customize_preview || $is_ajax_customize_save );
145
if ( ! $is_valid_request ) {
149
// Input from customizer preview.
150
if ( isset( $_POST['customized'] ) ) {
151
$this->_customized = json_decode( $this->get_post_value( 'customized' ), true );
152
} else { // Input from ajax widget update request.
153
$this->_customized = array();
154
$id_base = $this->get_post_value( 'id_base' );
155
$widget_number = $this->get_post_value( 'widget_number', false );
156
$option_name = 'widget_' . $id_base;
157
$this->_customized[ $option_name ] = array();
158
if ( preg_match( '/^[0-9]+$/', $widget_number ) ) {
159
$option_name .= '[' . $widget_number . ']';
160
$this->_customized[ $option_name ][ $widget_number ] = array();
164
$function = array( $this, 'prepreview_added_sidebars_widgets' );
166
$hook = 'option_sidebars_widgets';
167
add_filter( $hook, $function );
168
$this->_prepreview_added_filters[] = compact( 'hook', 'function' );
170
$hook = 'default_option_sidebars_widgets';
171
add_filter( $hook, $function );
172
$this->_prepreview_added_filters[] = compact( 'hook', 'function' );
174
$function = array( $this, 'prepreview_added_widget_instance' );
175
foreach ( $this->_customized as $setting_id => $value ) {
176
if ( preg_match( '/^(widget_.+?)(?:\[(\d+)\])?$/', $setting_id, $matches ) ) {
177
$option = $matches[1];
179
$hook = sprintf( 'option_%s', $option );
180
if ( ! has_filter( $hook, $function ) ) {
181
add_filter( $hook, $function );
182
$this->_prepreview_added_filters[] = compact( 'hook', 'function' );
185
$hook = sprintf( 'default_option_%s', $option );
186
if ( ! has_filter( $hook, $function ) ) {
187
add_filter( $hook, $function );
188
$this->_prepreview_added_filters[] = compact( 'hook', 'function' );
192
* Make sure the option is registered so that the update_option()
193
* won't fail due to the filters providing a default value, which
194
* causes the update_option() to get confused.
196
add_option( $option, array() );
202
* Ensure that newly-added widgets will appear in the widgets_sidebars.
204
* This is necessary because the customizer's setting preview filters
205
* are added after the widgets_init action, which is too late for the
206
* widgets to be set up properly.
211
* @param array $sidebars_widgets Associative array of sidebars and their widgets.
212
* @return array Filtered array of sidebars and their widgets.
214
public function prepreview_added_sidebars_widgets( $sidebars_widgets ) {
215
foreach ( $this->_customized as $setting_id => $value ) {
216
if ( preg_match( '/^sidebars_widgets\[(.+?)\]$/', $setting_id, $matches ) ) {
217
$sidebar_id = $matches[1];
218
$sidebars_widgets[ $sidebar_id ] = $value;
221
return $sidebars_widgets;
225
* Ensure newly-added widgets have empty instances so they
226
* will be recognized.
228
* This is necessary because the customizer's setting preview
229
* filters are added after the widgets_init action, which is
230
* too late for the widgets to be set up properly.
235
* @param array|bool|mixed $value Widget instance(s), false if open was empty.
236
* @return array|mixed Widget instance(s) with additions.
238
public function prepreview_added_widget_instance( $value = false ) {
239
if ( ! preg_match( '/^(?:default_)?option_(widget_(.+))/', current_filter(), $matches ) ) {
242
$id_base = $matches[2];
244
foreach ( $this->_customized as $setting_id => $setting ) {
245
$parsed_setting_id = $this->parse_widget_setting_id( $setting_id );
246
if ( is_wp_error( $parsed_setting_id ) || $id_base !== $parsed_setting_id['id_base'] ) {
249
$widget_number = $parsed_setting_id['number'];
251
if ( is_null( $widget_number ) ) {
253
if ( false === $value ) {
258
if ( empty( $value ) ) {
259
$value = array( '_multiwidget' => 1 );
261
if ( ! isset( $value[ $widget_number ] ) ) {
262
$value[ $widget_number ] = array();
271
* Remove pre-preview filters.
273
* Removes filters added in setup_widget_addition_previews()
274
* to ensure widgets are populating the options during
280
public function remove_prepreview_filters() {
281
foreach ( $this->_prepreview_added_filters as $prepreview_added_filter ) {
282
remove_filter( $prepreview_added_filter['hook'], $prepreview_added_filter['function'] );
284
$this->_prepreview_added_filters = array();
288
* Override sidebars_widgets for theme switch.
290
* When switching a theme via the customizer, supply any previously-configured
291
* sidebars_widgets from the target theme as the initial sidebars_widgets
292
* setting. Also store the old theme's existing settings so that they can
293
* be passed along for storing in the sidebars_widgets theme_mod when the
294
* theme gets switched.
299
public function override_sidebars_widgets_for_theme_switch() {
300
global $sidebars_widgets;
302
if ( $this->manager->doing_ajax() || $this->manager->is_theme_active() ) {
306
$this->old_sidebars_widgets = wp_get_sidebars_widgets();
307
add_filter( 'customize_value_old_sidebars_widgets_data', array( $this, 'filter_customize_value_old_sidebars_widgets_data' ) );
309
// retrieve_widgets() looks at the global $sidebars_widgets
310
$sidebars_widgets = $this->old_sidebars_widgets;
311
$sidebars_widgets = retrieve_widgets( 'customize' );
312
add_filter( 'option_sidebars_widgets', array( $this, 'filter_option_sidebars_widgets_for_theme_switch' ), 1 );
316
* Filter old_sidebars_widgets_data customizer setting.
318
* When switching themes, filter the Customizer setting
319
* old_sidebars_widgets_data to supply initial $sidebars_widgets before they
320
* were overridden by retrieve_widgets(). The value for
321
* old_sidebars_widgets_data gets set in the old theme's sidebars_widgets
324
* @see WP_Customize_Widgets::handle_theme_switch()
328
* @param array $sidebars_widgets
330
public function filter_customize_value_old_sidebars_widgets_data( $old_sidebars_widgets ) {
331
return $this->old_sidebars_widgets;
335
* Filter sidebars_widgets option for theme switch.
337
* When switching themes, the retrieve_widgets() function is run when the
338
* Customizer initializes, and then the new sidebars_widgets here get
339
* supplied as the default value for the sidebars_widgets option.
341
* @see WP_Customize_Widgets::handle_theme_switch()
345
* @param array $sidebars_widgets
347
public function filter_option_sidebars_widgets_for_theme_switch( $sidebars_widgets ) {
348
$sidebars_widgets = $GLOBALS['sidebars_widgets'];
349
$sidebars_widgets['array_version'] = 3;
350
return $sidebars_widgets;
354
* Make sure all widgets get loaded into the Customizer.
356
* Note: these actions are also fired in wp_ajax_update_widget().
361
public function customize_controls_init() {
362
/** This action is documented in wp-admin/includes/ajax-actions.php */
363
do_action( 'load-widgets.php' );
365
/** This action is documented in wp-admin/includes/ajax-actions.php */
366
do_action( 'widgets.php' );
368
/** This action is documented in wp-admin/widgets.php */
369
do_action( 'sidebar_admin_setup' );
373
* Ensure widgets are available for all types of previews.
375
* When in preview, hook to 'customize_register' for settings
376
* after WordPress is loaded so that all filters have been
377
* initialized (e.g. Widget Visibility).
382
public function schedule_customize_register() {
383
if ( is_admin() ) { // @todo for some reason, $wp_customize->is_preview() is true here?
384
$this->customize_register();
386
add_action( 'wp', array( $this, 'customize_register' ) );
391
* Register customizer settings and controls for all sidebars and widgets.
396
public function customize_register() {
397
global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_sidebars;
399
$sidebars_widgets = array_merge(
400
array( 'wp_inactive_widgets' => array() ),
401
array_fill_keys( array_keys( $GLOBALS['wp_registered_sidebars'] ), array() ),
402
wp_get_sidebars_widgets()
405
$new_setting_ids = array();
408
* Register a setting for all widgets, including those which are active,
409
* inactive, and orphaned since a widget may get suppressed from a sidebar
410
* via a plugin (like Widget Visibility).
412
foreach ( array_keys( $wp_registered_widgets ) as $widget_id ) {
413
$setting_id = $this->get_setting_id( $widget_id );
414
$setting_args = $this->get_setting_args( $setting_id );
416
$setting_args['sanitize_callback'] = array( $this, 'sanitize_widget_instance' );
417
$setting_args['sanitize_js_callback'] = array( $this, 'sanitize_widget_js_instance' );
419
$this->manager->add_setting( $setting_id, $setting_args );
421
$new_setting_ids[] = $setting_id;
425
* Add a setting which will be supplied for the theme's sidebars_widgets
426
* theme_mod when the the theme is switched.
428
if ( ! $this->manager->is_theme_active() ) {
429
$setting_id = 'old_sidebars_widgets_data';
430
$setting_args = $this->get_setting_args( $setting_id, array(
431
'type' => 'global_variable',
433
$this->manager->add_setting( $setting_id, $setting_args );
436
$this->manager->add_panel( 'widgets', array(
437
'title' => __( 'Widgets' ),
438
'description' => __( 'Widgets are independent sections of content that can be placed into widgetized areas provided by your theme (commonly called sidebars).' ),
442
foreach ( $sidebars_widgets as $sidebar_id => $sidebar_widget_ids ) {
443
if ( empty( $sidebar_widget_ids ) ) {
444
$sidebar_widget_ids = array();
447
$is_registered_sidebar = isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] );
448
$is_inactive_widgets = ( 'wp_inactive_widgets' === $sidebar_id );
449
$is_active_sidebar = ( $is_registered_sidebar && ! $is_inactive_widgets );
451
// Add setting for managing the sidebar's widgets.
452
if ( $is_registered_sidebar || $is_inactive_widgets ) {
453
$setting_id = sprintf( 'sidebars_widgets[%s]', $sidebar_id );
454
$setting_args = $this->get_setting_args( $setting_id );
456
$setting_args['sanitize_callback'] = array( $this, 'sanitize_sidebar_widgets' );
457
$setting_args['sanitize_js_callback'] = array( $this, 'sanitize_sidebar_widgets_js_instance' );
459
$this->manager->add_setting( $setting_id, $setting_args );
460
$new_setting_ids[] = $setting_id;
462
// Add section to contain controls.
463
$section_id = sprintf( 'sidebar-widgets-%s', $sidebar_id );
464
if ( $is_active_sidebar ) {
466
$section_args = array(
467
'title' => $GLOBALS['wp_registered_sidebars'][ $sidebar_id ]['name'],
468
'description' => $GLOBALS['wp_registered_sidebars'][ $sidebar_id ]['description'],
469
'priority' => array_search( $sidebar_id, array_keys( $wp_registered_sidebars ) ),
470
'panel' => 'widgets',
474
* Filter Customizer widget section arguments for a given sidebar.
478
* @param array $section_args Array of Customizer widget section arguments.
479
* @param string $section_id Customizer section ID.
480
* @param int|string $sidebar_id Sidebar ID.
482
$section_args = apply_filters( 'customizer_widgets_section_args', $section_args, $section_id, $sidebar_id );
484
$this->manager->add_section( $section_id, $section_args );
486
$control = new WP_Widget_Area_Customize_Control( $this->manager, $setting_id, array(
487
'section' => $section_id,
488
'sidebar_id' => $sidebar_id,
489
'priority' => count( $sidebar_widget_ids ), // place 'Add Widget' and 'Reorder' buttons at end.
491
$new_setting_ids[] = $setting_id;
493
$this->manager->add_control( $control );
497
// Add a control for each active widget (located in a sidebar).
498
foreach ( $sidebar_widget_ids as $i => $widget_id ) {
500
// Skip widgets that may have gone away due to a plugin being deactivated.
501
if ( ! $is_active_sidebar || ! isset( $GLOBALS['wp_registered_widgets'][$widget_id] ) ) {
505
$registered_widget = $GLOBALS['wp_registered_widgets'][$widget_id];
506
$setting_id = $this->get_setting_id( $widget_id );
507
$id_base = $GLOBALS['wp_registered_widget_controls'][$widget_id]['id_base'];
509
$control = new WP_Widget_Form_Customize_Control( $this->manager, $setting_id, array(
510
'label' => $registered_widget['name'],
511
'section' => $section_id,
512
'sidebar_id' => $sidebar_id,
513
'widget_id' => $widget_id,
514
'widget_id_base' => $id_base,
516
'width' => $wp_registered_widget_controls[$widget_id]['width'],
517
'height' => $wp_registered_widget_controls[$widget_id]['height'],
518
'is_wide' => $this->is_wide_widget( $widget_id ),
520
$this->manager->add_control( $control );
525
* We have to register these settings later than customize_preview_init
526
* so that other filters have had a chance to run.
528
if ( did_action( 'customize_preview_init' ) ) {
529
foreach ( $new_setting_ids as $new_setting_id ) {
530
$this->manager->get_setting( $new_setting_id )->preview();
533
$this->remove_prepreview_filters();
537
* Covert a widget_id into its corresponding customizer setting ID (option name).
542
* @param string $widget_id Widget ID.
543
* @return string Maybe-parsed widget ID.
545
public function get_setting_id( $widget_id ) {
546
$parsed_widget_id = $this->parse_widget_id( $widget_id );
547
$setting_id = sprintf( 'widget_%s', $parsed_widget_id['id_base'] );
549
if ( ! is_null( $parsed_widget_id['number'] ) ) {
550
$setting_id .= sprintf( '[%d]', $parsed_widget_id['number'] );
556
* Determine whether the widget is considered "wide".
558
* Core widgets which may have controls wider than 250, but can
559
* still be shown in the narrow customizer panel. The RSS and Text
560
* widgets in Core, for example, have widths of 400 and yet they
561
* still render fine in the customizer panel. This method will
562
* return all Core widgets as being not wide, but this can be
563
* overridden with the is_wide_widget_in_customizer filter.
568
* @param string $widget_id Widget ID.
569
* @return bool Whether or not the widget is a "wide" widget.
571
public function is_wide_widget( $widget_id ) {
572
global $wp_registered_widget_controls;
574
$parsed_widget_id = $this->parse_widget_id( $widget_id );
575
$width = $wp_registered_widget_controls[$widget_id]['width'];
576
$is_core = in_array( $parsed_widget_id['id_base'], $this->core_widget_id_bases );
577
$is_wide = ( $width > 250 && ! $is_core );
580
* Filter whether the given widget is considered "wide".
584
* @param bool $is_wide Whether the widget is wide, Default false.
585
* @param string $widget_id Widget ID.
587
return apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id );
591
* Covert a widget ID into its id_base and number components.
596
* @param string $widget_id Widget ID.
597
* @return array Array containing a widget's id_base and number components.
599
public function parse_widget_id( $widget_id ) {
605
if ( preg_match( '/^(.+)-(\d+)$/', $widget_id, $matches ) ) {
606
$parsed['id_base'] = $matches[1];
607
$parsed['number'] = intval( $matches[2] );
609
// likely an old single widget
610
$parsed['id_base'] = $widget_id;
616
* Convert a widget setting ID (option path) to its id_base and number components.
621
* @param string $setting_id Widget setting ID.
622
* @return WP_Error|array Array containing a widget's id_base and number components,
623
* or a WP_Error object.
625
public function parse_widget_setting_id( $setting_id ) {
626
if ( ! preg_match( '/^(widget_(.+?))(?:\[(\d+)\])?$/', $setting_id, $matches ) ) {
627
return new WP_Error( 'widget_setting_invalid_id' );
630
$id_base = $matches[2];
631
$number = isset( $matches[3] ) ? intval( $matches[3] ) : null;
633
return compact( 'id_base', 'number' );
637
* Call admin_print_styles-widgets.php and admin_print_styles hooks to
638
* allow custom styles from plugins.
643
public function print_styles() {
644
/** This action is documented in wp-admin/admin-header.php */
645
do_action( 'admin_print_styles-widgets.php' );
647
/** This action is documented in wp-admin/admin-header.php */
648
do_action( 'admin_print_styles' );
652
* Call admin_print_scripts-widgets.php and admin_print_scripts hooks to
653
* allow custom scripts from plugins.
658
public function print_scripts() {
659
/** This action is documented in wp-admin/admin-header.php */
660
do_action( 'admin_print_scripts-widgets.php' );
662
/** This action is documented in wp-admin/admin-header.php */
663
do_action( 'admin_print_scripts' );
667
* Enqueue scripts and styles for customizer panel and export data to JavaScript.
672
public function enqueue_scripts() {
673
wp_enqueue_style( 'customize-widgets' );
674
wp_enqueue_script( 'customize-widgets' );
676
/** This action is documented in wp-admin/admin-header.php */
677
do_action( 'admin_enqueue_scripts', 'widgets.php' );
680
* Export available widgets with control_tpl removed from model
681
* since plugins need templates to be in the DOM.
683
$available_widgets = array();
685
foreach ( $this->get_available_widgets() as $available_widget ) {
686
unset( $available_widget['control_tpl'] );
687
$available_widgets[] = $available_widget;
690
$widget_reorder_nav_tpl = sprintf(
691
'<div class="widget-reorder-nav"><span class="move-widget" tabindex="0">%1$s</span><span class="move-widget-down" tabindex="0">%2$s</span><span class="move-widget-up" tabindex="0">%3$s</span></div>',
692
__( 'Move to another area…' ),
697
$move_widget_area_tpl = str_replace(
698
array( '{description}', '{btn}' ),
700
__( 'Select an area to move this widget into:' ),
701
_x( 'Move', 'Move widget' ),
703
'<div class="move-widget-area">
704
<p class="description">{description}</p>
705
<ul class="widget-area-select">
706
<% _.each( sidebars, function ( sidebar ){ %>
707
<li class="" data-id="<%- sidebar.id %>" title="<%- sidebar.description %>" tabindex="0"><%- sidebar.name %></li>
710
<div class="move-widget-actions">
711
<button class="move-widget-btn button-secondary" type="button">{btn}</button>
719
'nonce' => wp_create_nonce( 'update-widget' ),
720
'registeredSidebars' => array_values( $GLOBALS['wp_registered_sidebars'] ),
721
'registeredWidgets' => $GLOBALS['wp_registered_widgets'],
722
'availableWidgets' => $available_widgets, // @todo Merge this with registered_widgets
724
'saveBtnLabel' => __( 'Apply' ),
725
'saveBtnTooltip' => __( 'Save and preview changes before publishing them.' ),
726
'removeBtnLabel' => __( 'Remove' ),
727
'removeBtnTooltip' => __( 'Trash widget by moving it to the inactive widgets sidebar.' ),
728
'error' => __( 'An error has occurred. Please reload the page and try again.' ),
731
'widgetReorderNav' => $widget_reorder_nav_tpl,
732
'moveWidgetArea' => $move_widget_area_tpl,
736
foreach ( $settings['registeredWidgets'] as &$registered_widget ) {
737
unset( $registered_widget['callback'] ); // may not be JSON-serializeable
740
$wp_scripts->add_data(
743
sprintf( 'var _wpCustomizeWidgetsSettings = %s;', json_encode( $settings ) )
748
* Render the widget form control templates into the DOM.
753
public function output_widget_control_templates() {
755
<div id="widgets-left"><!-- compatibility with JS which looks for widget templates here -->
756
<div id="available-widgets">
757
<div id="available-widgets-filter">
758
<label class="screen-reader-text" for="widgets-search"><?php _e( 'Search Widgets' ); ?></label>
759
<input type="search" id="widgets-search" placeholder="<?php esc_attr_e( 'Search widgets…' ) ?>" />
761
<?php foreach ( $this->get_available_widgets() as $available_widget ): ?>
762
<div id="widget-tpl-<?php echo esc_attr( $available_widget['id'] ) ?>" data-widget-id="<?php echo esc_attr( $available_widget['id'] ) ?>" class="widget-tpl <?php echo esc_attr( $available_widget['id'] ) ?>" tabindex="0">
763
<?php echo $available_widget['control_tpl']; ?>
766
</div><!-- #available-widgets -->
767
</div><!-- #widgets-left -->
772
* Call admin_print_footer_scripts and admin_print_scripts hooks to
773
* allow custom scripts from plugins.
778
public function print_footer_scripts() {
779
/** This action is documented in wp-admin/admin-footer.php */
780
do_action( 'admin_print_footer_scripts' );
782
/** This action is documented in wp-admin/admin-footer.php */
783
do_action( 'admin_footer-widgets.php' );
787
* Get common arguments to supply when constructing a Customizer setting.
792
* @param string $id Widget setting ID.
793
* @param array $overrides Array of setting overrides.
794
* @return array Possibly modified setting arguments.
796
public function get_setting_args( $id, $overrides = array() ) {
799
'capability' => 'edit_theme_options',
800
'transport' => 'refresh',
801
'default' => array(),
803
$args = array_merge( $args, $overrides );
806
* Filter the common arguments supplied when constructing a Customizer setting.
810
* @see WP_Customize_Setting
812
* @param array $args Array of Customizer setting arguments.
813
* @param string $id Widget setting ID.
815
return apply_filters( 'widget_customizer_setting_args', $args, $id );
819
* Make sure that sidebar widget arrays only ever contain widget IDS.
821
* Used as the 'sanitize_callback' for each $sidebars_widgets setting.
826
* @param array $widget_ids Array of widget IDs.
827
* @return array Array of sanitized widget IDs.
829
public function sanitize_sidebar_widgets( $widget_ids ) {
830
global $wp_registered_widgets;
832
$widget_ids = array_map( 'strval', (array) $widget_ids );
833
$sanitized_widget_ids = array();
835
foreach ( $widget_ids as $widget_id ) {
836
if ( array_key_exists( $widget_id, $wp_registered_widgets ) ) {
837
$sanitized_widget_ids[] = $widget_id;
840
return $sanitized_widget_ids;
844
* Build up an index of all available widgets for use in Backbone models.
849
* @see wp_list_widgets()
851
* @return array List of available widgets.
853
public function get_available_widgets() {
854
static $available_widgets = array();
855
if ( ! empty( $available_widgets ) ) {
856
return $available_widgets;
859
global $wp_registered_widgets, $wp_registered_widget_controls;
860
require_once ABSPATH . '/wp-admin/includes/widgets.php'; // for next_widget_id_number()
862
$sort = $wp_registered_widgets;
863
usort( $sort, array( $this, '_sort_name_callback' ) );
866
foreach ( $sort as $widget ) {
867
if ( in_array( $widget['callback'], $done, true ) ) { // We already showed this multi-widget
871
$sidebar = is_active_widget( $widget['callback'], $widget['id'], false, false );
872
$done[] = $widget['callback'];
874
if ( ! isset( $widget['params'][0] ) ) {
875
$widget['params'][0] = array();
878
$available_widget = $widget;
879
unset( $available_widget['callback'] ); // not serializable to JSON
882
'widget_id' => $widget['id'],
883
'widget_name' => $widget['name'],
884
'_display' => 'template',
887
$is_disabled = false;
888
$is_multi_widget = ( isset( $wp_registered_widget_controls[$widget['id']]['id_base'] ) && isset( $widget['params'][0]['number'] ) );
889
if ( $is_multi_widget ) {
890
$id_base = $wp_registered_widget_controls[$widget['id']]['id_base'];
891
$args['_temp_id'] = "$id_base-__i__";
892
$args['_multi_num'] = next_widget_id_number( $id_base );
893
$args['_add'] = 'multi';
895
$args['_add'] = 'single';
897
if ( $sidebar && 'wp_inactive_widgets' !== $sidebar ) {
900
$id_base = $widget['id'];
903
$list_widget_controls_args = wp_list_widget_controls_dynamic_sidebar( array( 0 => $args, 1 => $widget['params'][0] ) );
904
$control_tpl = $this->get_widget_control( $list_widget_controls_args );
906
// The properties here are mapped to the Backbone Widget model.
907
$available_widget = array_merge( $available_widget, array(
908
'temp_id' => isset( $args['_temp_id'] ) ? $args['_temp_id'] : null,
909
'is_multi' => $is_multi_widget,
910
'control_tpl' => $control_tpl,
911
'multi_number' => ( $args['_add'] === 'multi' ) ? $args['_multi_num'] : false,
912
'is_disabled' => $is_disabled,
913
'id_base' => $id_base,
914
'transport' => 'refresh',
915
'width' => $wp_registered_widget_controls[$widget['id']]['width'],
916
'height' => $wp_registered_widget_controls[$widget['id']]['height'],
917
'is_wide' => $this->is_wide_widget( $widget['id'] ),
920
$available_widgets[] = $available_widget;
923
return $available_widgets;
927
* Naturally order available widgets by name.
933
* @param array $widget_a The first widget to compare.
934
* @param array $widget_b The second widget to compare.
935
* @return int Reorder position for the current widget comparison.
937
protected function _sort_name_callback( $widget_a, $widget_b ) {
938
return strnatcasecmp( $widget_a['name'], $widget_b['name'] );
942
* Get the widget control markup.
947
* @param array $args Widget control arguments.
948
* @return string Widget control form HTML markup.
950
public function get_widget_control( $args ) {
953
call_user_func_array( 'wp_widget_control', $args );
954
$replacements = array(
955
'<form action="" method="post">' => '<div class="form">',
956
'</form>' => '</div><!-- .form -->',
959
$control_tpl = ob_get_clean();
961
$control_tpl = str_replace( array_keys( $replacements ), array_values( $replacements ), $control_tpl );
967
* Add hooks for the customizer preview.
972
public function customize_preview_init() {
973
add_filter( 'sidebars_widgets', array( $this, 'preview_sidebars_widgets' ), 1 );
974
add_action( 'wp_enqueue_scripts', array( $this, 'customize_preview_enqueue' ) );
975
add_action( 'wp_print_styles', array( $this, 'print_preview_css' ), 1 );
976
add_action( 'wp_footer', array( $this, 'export_preview_data' ), 20 );
980
* When previewing, make sure the proper previewing widgets are used.
982
* Because wp_get_sidebars_widgets() gets called early at init
983
* (via wp_convert_widget_settings()) and can set global variable
984
* $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' )
985
* before the customizer preview filter is added, we have to reset
986
* it after the filter has been added.
991
* @param array $sidebars_widgets List of widgets for the current sidebar.
993
public function preview_sidebars_widgets( $sidebars_widgets ) {
994
$sidebars_widgets = get_option( 'sidebars_widgets' );
996
unset( $sidebars_widgets['array_version'] );
997
return $sidebars_widgets;
1001
* Enqueue scripts for the Customizer preview.
1006
public function customize_preview_enqueue() {
1007
wp_enqueue_script( 'customize-preview-widgets' );
1011
* Insert default style for highlighted widget at early point so theme
1012
* stylesheet can override.
1017
* @action wp_print_styles
1019
public function print_preview_css() {
1022
.widget-customizer-highlighted-widget {
1024
-webkit-box-shadow: 0 0 2px rgba(30,140,190,0.8);
1025
box-shadow: 0 0 2px rgba(30,140,190,0.8);
1034
* At the very end of the page, at the very end of the wp_footer,
1035
* communicate the sidebars that appeared on the page.
1040
public function export_preview_data() {
1042
// Prepare customizer settings to pass to Javascript.
1044
'renderedSidebars' => array_fill_keys( array_unique( $this->rendered_sidebars ), true ),
1045
'renderedWidgets' => array_fill_keys( array_keys( $this->rendered_widgets ), true ),
1046
'registeredSidebars' => array_values( $GLOBALS['wp_registered_sidebars'] ),
1047
'registeredWidgets' => $GLOBALS['wp_registered_widgets'],
1049
'widgetTooltip' => __( 'Shift-click to edit this widget.' ),
1052
foreach ( $settings['registeredWidgets'] as &$registered_widget ) {
1053
unset( $registered_widget['callback'] ); // may not be JSON-serializeable
1057
<script type="text/javascript">
1058
var _wpWidgetCustomizerPreviewSettings = <?php echo json_encode( $settings ); ?>;
1064
* Keep track of the widgets that were rendered.
1069
* @param array $widget Rendered widget to tally.
1071
public function tally_rendered_widgets( $widget ) {
1072
$this->rendered_widgets[ $widget['id'] ] = true;
1076
* Determine if a widget is rendered on the page.
1081
* @param string $widget_id Widget ID to check.
1082
* @return bool Whether the widget is rendered.
1084
public function is_widget_rendered( $widget_id ) {
1085
return in_array( $widget_id, $this->rendered_widgets );
1089
* Determine if a sidebar is rendered on the page.
1094
* @param string $sidebar_id Sidebar ID to check.
1095
* @return bool Whether the sidebar is rendered.
1097
public function is_sidebar_rendered( $sidebar_id ) {
1098
return in_array( $sidebar_id, $this->rendered_sidebars );
1102
* Tally the sidebars rendered via is_active_sidebar().
1104
* Keep track of the times that is_active_sidebar() is called
1105
* in the template, and assume that this means that the sidebar
1106
* would be rendered on the template if there were widgets
1112
* @param bool $is_active Whether the sidebar is active.
1113
* @param string $sidebar_id Sidebar ID.
1115
public function tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id ) {
1116
if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
1117
$this->rendered_sidebars[] = $sidebar_id;
1120
* We may need to force this to true, and also force-true the value
1121
* for 'dynamic_sidebar_has_widgets' if we want to ensure that there
1122
* is an area to drop widgets into, if the sidebar is empty.
1128
* Tally the sidebars rendered via dynamic_sidebar().
1130
* Keep track of the times that dynamic_sidebar() is called in the template,
1131
* and assume this means the sidebar would be rendered on the template if
1132
* there were widgets populating it.
1137
* @param bool $has_widgets Whether the current sidebar has widgets.
1138
* @param string $sidebar_id Sidebar ID.
1140
public function tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id ) {
1141
if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
1142
$this->rendered_sidebars[] = $sidebar_id;
1146
* We may need to force this to true, and also force-true the value
1147
* for 'is_active_sidebar' if we want to ensure there is an area to
1148
* drop widgets into, if the sidebar is empty.
1150
return $has_widgets;
1154
* Get MAC for a serialized widget instance string.
1156
* Allows values posted back from JS to be rejected if any tampering of the
1157
* data has occurred.
1162
* @param string $serialized_instance Widget instance.
1163
* @return string MAC for serialized widget instance.
1165
protected function get_instance_hash_key( $serialized_instance ) {
1166
return wp_hash( $serialized_instance );
1170
* Sanitize a widget instance.
1172
* Unserialize the JS-instance for storing in the options. It's important
1173
* that this filter only get applied to an instance once.
1178
* @param array $value Widget instance to sanitize.
1179
* @return array Sanitized widget instance.
1181
public function sanitize_widget_instance( $value ) {
1182
if ( $value === array() ) {
1186
if ( empty( $value['is_widget_customizer_js_value'] )
1187
|| empty( $value['instance_hash_key'] )
1188
|| empty( $value['encoded_serialized_instance'] ) )
1193
$decoded = base64_decode( $value['encoded_serialized_instance'], true );
1194
if ( false === $decoded ) {
1198
if ( $this->get_instance_hash_key( $decoded ) !== $value['instance_hash_key'] ) {
1202
$instance = unserialize( $decoded );
1203
if ( false === $instance ) {
1211
* Convert widget instance into JSON-representable format.
1216
* @param array $value Widget instance to convert to JSON.
1217
* @return array JSON-converted widget instance.
1219
public function sanitize_widget_js_instance( $value ) {
1220
if ( empty( $value['is_widget_customizer_js_value'] ) ) {
1221
$serialized = serialize( $value );
1224
'encoded_serialized_instance' => base64_encode( $serialized ),
1225
'title' => empty( $value['title'] ) ? '' : $value['title'],
1226
'is_widget_customizer_js_value' => true,
1227
'instance_hash_key' => $this->get_instance_hash_key( $serialized ),
1234
* Strip out widget IDs for widgets which are no longer registered.
1236
* One example where this might happen is when a plugin orphans a widget
1237
* in a sidebar upon deactivation.
1242
* @param array $widget_ids List of widget IDs.
1243
* @return array Parsed list of widget IDs.
1245
public function sanitize_sidebar_widgets_js_instance( $widget_ids ) {
1246
global $wp_registered_widgets;
1247
$widget_ids = array_values( array_intersect( $widget_ids, array_keys( $wp_registered_widgets ) ) );
1252
* Find and invoke the widget update and control callbacks.
1254
* Requires that $_POST be populated with the instance data.
1259
* @param string $widget_id Widget ID.
1260
* @return WP_Error|array Array containing the updated widget information.
1261
* A WP_Error object, otherwise.
1263
public function call_widget_update( $widget_id ) {
1264
global $wp_registered_widget_updates, $wp_registered_widget_controls;
1266
$this->start_capturing_option_updates();
1267
$parsed_id = $this->parse_widget_id( $widget_id );
1268
$option_name = 'widget_' . $parsed_id['id_base'];
1271
* If a previously-sanitized instance is provided, populate the input vars
1272
* with its values so that the widget update callback will read this instance
1274
$added_input_vars = array();
1275
if ( ! empty( $_POST['sanitized_widget_setting'] ) ) {
1276
$sanitized_widget_setting = json_decode( $this->get_post_value( 'sanitized_widget_setting' ), true );
1277
if ( false === $sanitized_widget_setting ) {
1278
$this->stop_capturing_option_updates();
1279
return new WP_Error( 'widget_setting_malformed' );
1282
$instance = $this->sanitize_widget_instance( $sanitized_widget_setting );
1283
if ( is_null( $instance ) ) {
1284
$this->stop_capturing_option_updates();
1285
return new WP_Error( 'widget_setting_unsanitized' );
1288
if ( ! is_null( $parsed_id['number'] ) ) {
1290
$value[$parsed_id['number']] = $instance;
1291
$key = 'widget-' . $parsed_id['id_base'];
1292
$_REQUEST[$key] = $_POST[$key] = wp_slash( $value );
1293
$added_input_vars[] = $key;
1295
foreach ( $instance as $key => $value ) {
1296
$_REQUEST[$key] = $_POST[$key] = wp_slash( $value );
1297
$added_input_vars[] = $key;
1302
// Invoke the widget update callback.
1303
foreach ( (array) $wp_registered_widget_updates as $name => $control ) {
1304
if ( $name === $parsed_id['id_base'] && is_callable( $control['callback'] ) ) {
1306
call_user_func_array( $control['callback'], $control['params'] );
1312
// Clean up any input vars that were manually added
1313
foreach ( $added_input_vars as $key ) {
1314
unset( $_POST[$key] );
1315
unset( $_REQUEST[$key] );
1318
// Make sure the expected option was updated.
1319
if ( 0 !== $this->count_captured_options() ) {
1320
if ( $this->count_captured_options() > 1 ) {
1321
$this->stop_capturing_option_updates();
1322
return new WP_Error( 'widget_setting_too_many_options' );
1325
$updated_option_name = key( $this->get_captured_options() );
1326
if ( $updated_option_name !== $option_name ) {
1327
$this->stop_capturing_option_updates();
1328
return new WP_Error( 'widget_setting_unexpected_option' );
1332
// Obtain the widget control with the updated instance in place.
1335
$form = $wp_registered_widget_controls[$widget_id];
1337
call_user_func_array( $form['callback'], $form['params'] );
1340
$form = ob_get_clean();
1342
// Obtain the widget instance.
1343
$option = get_option( $option_name );
1345
if ( null !== $parsed_id['number'] ) {
1346
$instance = $option[$parsed_id['number']];
1348
$instance = $option;
1351
$this->stop_capturing_option_updates();
1353
return compact( 'instance', 'form' );
1357
* Update widget settings asynchronously.
1359
* Allows the Customizer to update a widget using its form, but return the new
1360
* instance info via Ajax instead of saving it to the options table.
1362
* Most code here copied from wp_ajax_save_widget()
1367
* @see wp_ajax_save_widget()
1370
public function wp_ajax_update_widget() {
1372
if ( ! is_user_logged_in() ) {
1376
check_ajax_referer( 'update-widget', 'nonce' );
1378
if ( ! current_user_can( 'edit_theme_options' ) ) {
1382
if ( ! isset( $_POST['widget-id'] ) ) {
1383
wp_send_json_error();
1386
/** This action is documented in wp-admin/includes/ajax-actions.php */
1387
do_action( 'load-widgets.php' );
1389
/** This action is documented in wp-admin/includes/ajax-actions.php */
1390
do_action( 'widgets.php' );
1392
/** This action is documented in wp-admin/widgets.php */
1393
do_action( 'sidebar_admin_setup' );
1395
$widget_id = $this->get_post_value( 'widget-id' );
1396
$parsed_id = $this->parse_widget_id( $widget_id );
1397
$id_base = $parsed_id['id_base'];
1399
if ( isset( $_POST['widget-' . $id_base] ) && is_array( $_POST['widget-' . $id_base] ) && preg_match( '/__i__|%i%/', key( $_POST['widget-' . $id_base] ) ) ) {
1400
wp_send_json_error();
1403
$updated_widget = $this->call_widget_update( $widget_id ); // => {instance,form}
1404
if ( is_wp_error( $updated_widget ) ) {
1405
wp_send_json_error();
1408
$form = $updated_widget['form'];
1409
$instance = $this->sanitize_widget_js_instance( $updated_widget['instance'] );
1411
wp_send_json_success( compact( 'form', 'instance' ) );
1414
/***************************************************************************
1415
* Option Update Capturing
1416
***************************************************************************/
1419
* List of captured widget option updates.
1423
* @var array $_captured_options Values updated while option capture is happening.
1425
protected $_captured_options = array();
1428
* Whether option capture is currently happening.
1432
* @var bool $_is_current Whether option capture is currently happening or not.
1434
protected $_is_capturing_option_updates = false;
1437
* Determine whether the captured option update should be ignored.
1442
* @param string $option_name Option name.
1443
* @return boolean Whether the option capture is ignored.
1445
protected function is_option_capture_ignored( $option_name ) {
1446
return ( 0 === strpos( $option_name, '_transient_' ) );
1450
* Retrieve captured widget option updates.
1455
* @return array Array of captured options.
1457
protected function get_captured_options() {
1458
return $this->_captured_options;
1462
* Get the number of captured widget option updates.
1467
* @return int Number of updated options.
1469
protected function count_captured_options() {
1470
return count( $this->_captured_options );
1474
* Start keeping track of changes to widget options, caching new values.
1479
protected function start_capturing_option_updates() {
1480
if ( $this->_is_capturing_option_updates ) {
1484
$this->_is_capturing_option_updates = true;
1486
add_filter( 'pre_update_option', array( $this, 'capture_filter_pre_update_option' ), 10, 3 );
1490
* Pre-filter captured option values before updating.
1495
* @param mixed $new_value
1496
* @param string $option_name
1497
* @param mixed $old_value
1500
public function capture_filter_pre_update_option( $new_value, $option_name, $old_value ) {
1501
if ( $this->is_option_capture_ignored( $option_name ) ) {
1505
if ( ! isset( $this->_captured_options[$option_name] ) ) {
1506
add_filter( "pre_option_{$option_name}", array( $this, 'capture_filter_pre_get_option' ) );
1509
$this->_captured_options[$option_name] = $new_value;
1515
* Pre-filter captured option values before retrieving.
1520
* @param mixed $value Option
1523
public function capture_filter_pre_get_option( $value ) {
1524
$option_name = preg_replace( '/^pre_option_/', '', current_filter() );
1526
if ( isset( $this->_captured_options[$option_name] ) ) {
1527
$value = $this->_captured_options[$option_name];
1529
/** This filter is documented in wp-includes/option.php */
1530
$value = apply_filters( 'option_' . $option_name, $value );
1537
* Undo any changes to the options since options capture began.
1542
protected function stop_capturing_option_updates() {
1543
if ( ! $this->_is_capturing_option_updates ) {
1547
remove_filter( 'pre_update_option', array( $this, 'capture_filter_pre_update_option' ), 10, 3 );
1549
foreach ( array_keys( $this->_captured_options ) as $option_name ) {
1550
remove_filter( "pre_option_{$option_name}", array( $this, 'capture_filter_pre_get_option' ) );
1553
$this->_captured_options = array();
1554
$this->_is_capturing_option_updates = false;
added
removed
wp-includes/class-wp-customize-widgets.php
