WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Second-pass inline documentation improvements for WP_Customize_Widgets. 

See #27534.

Built from https://develop.svn.wordpress.org/trunk@27903


git-svn-id: http://core.svn.wordpress.org/trunk@27734 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Drew Jaynes 2014-04-02 05:45:16 +00:00
parent 3d2728f7a6
commit 44c886045f
1 changed files with 193 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

296
wp-includes/class-wp-customize-widgets.php
View File

@ -9,14 +9,18 @@
* @since 3.9.0 * @since 3.9.0
*/ */
final class WP_Customize_Widgets { final class WP_Customize_Widgets {
/** /**
* WP_Customize_Manager instance.
*
* @since 3.9.0
* @access public * @access public
* @var WP_Customize_Manager * @var WP_Customize_Manager
*/ */
public $manager; public $manager;
/** /**
* All id_bases for widgets defined in core * All id_bases for widgets defined in core.
* *
* @since 3.9.0 * @since 3.9.0
* @access protected * @access protected
@ -71,6 +75,8 @@ final class WP_Customize_Widgets {
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
*
* @param WP_Customize_Manager $manager Customize manager bootstrap instance.
*/ */
public function __construct( WP_Customize_Manager $manager ) { public function __construct( WP_Customize_Manager $manager ) {
$this->manager = $manager; $this->manager = $manager;
@ -107,15 +113,16 @@ final class WP_Customize_Widgets {
} }
/** /**
* Set up widget addition previews.
* *
* * Since the widgets get registered on 'widgets_init' before the customizer
* Since the widgets get registered (widgets_init) before the customizer settings are set up (customize_register), * settings are set up on 'customize_register', we have to filter the options
* we have to filter the options similarly to how the setting previewer will filter the options later. * similarly to how the setting previewer will filter the options later.
* *
* @since 3.9.0 * @since 3.9.0
* *
* @access public * @access public
* @global WP_Customize_Manager $wp_customize * @global WP_Customize_Manager $wp_customize Customizer instance.
*/ */
public function setup_widget_addition_previews() { public function setup_widget_addition_previews() {
$is_customize_preview = false; $is_customize_preview = false;
@ -168,15 +175,20 @@ final class WP_Customize_Widgets {
foreach ( $customized as $setting_id => $value ) { foreach ( $customized as $setting_id => $value ) {
if ( preg_match( '/^(widget_.+?)(\[(\d+)\])?$/', $setting_id, $matches ) ) { if ( preg_match( '/^(widget_.+?)(\[(\d+)\])?$/', $setting_id, $matches ) ) {
/*
* @todo Replace the next two lines with the following once WordPress supports PHP 5.3.
*
* $self = $this; // not needed in PHP 5.4
*
* $function = function ( $value ) use ( $self, $setting_id ) {
* return $self->manager->widgets->prepreview_added_widget_instance( $value, $setting_id );
* };
*/
$body = sprintf( 'global $wp_customize; return $wp_customize->widgets->prepreview_added_widget_instance( $value, %s );', var_export( $setting_id, true ) ); $body = sprintf( 'global $wp_customize; return $wp_customize->widgets->prepreview_added_widget_instance( $value, %s );', var_export( $setting_id, true ) );
$function = create_function( '$value', $body ); $function = create_function( '$value', $body );
// @todo replace above two lines with following once PHP 5.3 happens in WordPress
// $self = $this; // not needed in PHP 5.4
// $function = function ( $value ) use ( $self, $setting_id ) {
// return $self->manager->widgets->prepreview_added_widget_instance( $value, $setting_id );
//};
$option = $matches[1]; $option = $matches[1];
$hook = sprintf( 'option_%s', $option ); $hook = sprintf( 'option_%s', $option );
add_filter( $hook, $function ); add_filter( $hook, $function );
@ -186,9 +198,10 @@ final class WP_Customize_Widgets {
add_filter( $hook, $function ); add_filter( $hook, $function );
$this->_prepreview_added_filters[] = compact( 'hook', 'function' ); $this->_prepreview_added_filters[] = compact( 'hook', 'function' );
/** /*
* Make sure the option is registered so that the update_option won't fail due to * Make sure the option is registered so that the update_option()
* the filters providing a default value, which causes the update_option() to get confused. * won't fail due to the filters providing a default value, which
* causes the update_option() to get confused.
*/ */
add_option( $option, array() ); add_option( $option, array() );
} }
@ -198,17 +211,17 @@ final class WP_Customize_Widgets {
} }
/** /**
*
*
* Ensure that newly-added widgets will appear in the widgets_sidebars. * Ensure that newly-added widgets will appear in the widgets_sidebars.
* This is necessary because the customizer's setting preview filters are added after the widgets_init action, *
* which is too late for the widgets to be set up properly. * This is necessary because the customizer's setting preview filters
* are added after the widgets_init action, which is too late for the
* widgets to be set up properly.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
* *
* @param array $sidebars_widgets Array of * @param array $sidebars_widgets Associative array of sidebars and their widgets.
* @return array * @return array Filtered array of sidebars and their widgets.
*/ */
public function prepreview_added_sidebars_widgets( $sidebars_widgets ) { public function prepreview_added_sidebars_widgets( $sidebars_widgets ) {
foreach ( $this->_customized as $setting_id => $value ) { foreach ( $this->_customized as $setting_id => $value ) {
@ -221,11 +234,12 @@ final class WP_Customize_Widgets {
} }
/** /**
* Ensure newly-added widgets have empty instances so they
* will be recognized.
* *
* * This is necessary because the customizer's setting preview
* Ensure that newly-added widgets will have empty instances so that they will be recognized. * filters are added after the widgets_init action, which is
* This is necessary because the customizer's setting preview filters are added after the widgets_init action, * too late for the widgets to be set up properly.
* which is too late for the widgets to be set up properly.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -239,7 +253,7 @@ final class WP_Customize_Widgets {
$parsed_setting_id = $this->parse_widget_setting_id( $setting_id ); $parsed_setting_id = $this->parse_widget_setting_id( $setting_id );
$widget_number = $parsed_setting_id['number']; $widget_number = $parsed_setting_id['number'];
// Single widget // Single widget.
if ( is_null( $widget_number ) ) { if ( is_null( $widget_number ) ) {
if ( false === $instance && empty( $value ) ) { if ( false === $instance && empty( $value ) ) {
$instance = array(); $instance = array();
@ -259,8 +273,11 @@ final class WP_Customize_Widgets {
} }
/** /**
* Remove filters added in setup_widget_addition_previews() which ensure that * Remove pre-preview filters.
* widgets are populating the options during widgets_init *
* Removes filters added in setup_widget_addition_previews()
* to ensure widgets are populating the options during
* 'widgets_init'.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -273,13 +290,18 @@ final class WP_Customize_Widgets {
} }
/** /**
* Make sure that all widgets get loaded into customizer; these actions are also done in the wp_ajax_save_widget() * Make sure all widgets get loaded into the Customizer.
*
* Note: these actions are also fired in wp_ajax_update_widget().
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
*/ */
public function customize_controls_init() { public function customize_controls_init() {
/** This action is documented in wp-admin/includes/ajax-actions.php */
do_action( 'load-widgets.php' ); do_action( 'load-widgets.php' );
/** This action is documented in wp-admin/includes/ajax-actions.php */
do_action( 'widgets.php' ); do_action( 'widgets.php' );
/** This action is documented in wp-admin/widgets.php */ /** This action is documented in wp-admin/widgets.php */
@ -287,8 +309,11 @@ final class WP_Customize_Widgets {
} }
/** /**
* When in preview, invoke customize_register for settings after WordPress is * Ensure widgets are available for all types of previews.
* loaded so that all filters have been initialized (e.g. Widget Visibility) *
* When in preview, hook to 'customize_register' for settings
* after WordPress is loaded so that all filters have been
* initialized (e.g. Widget Visibility).
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -302,7 +327,7 @@ final class WP_Customize_Widgets {
} }
/** /**
* Register customizer settings and controls for all sidebars and widgets * Register customizer settings and controls for all sidebars and widgets.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -319,8 +344,9 @@ final class WP_Customize_Widgets {
$new_setting_ids = array(); $new_setting_ids = array();
/* /*
* Register a setting for all widgets, including those which are active, inactive, and orphaned * Register a setting for all widgets, including those which are active,
* since a widget may get suppressed from a sidebar via a plugin (like Widget Visibility). * inactive, and orphaned since a widget may get suppressed from a sidebar
* via a plugin (like Widget Visibility).
*/ */
foreach ( array_keys( $wp_registered_widgets ) as $widget_id ) { foreach ( array_keys( $wp_registered_widgets ) as $widget_id ) {
$setting_id = $this->get_setting_id( $widget_id ); $setting_id = $this->get_setting_id( $widget_id );
@ -339,9 +365,7 @@ final class WP_Customize_Widgets {
$is_inactive_widgets = ( 'wp_inactive_widgets' === $sidebar_id ); $is_inactive_widgets = ( 'wp_inactive_widgets' === $sidebar_id );
$is_active_sidebar = ( $is_registered_sidebar && ! $is_inactive_widgets ); $is_active_sidebar = ( $is_registered_sidebar && ! $is_inactive_widgets );
/** // Add setting for managing the sidebar's widgets.
* Add setting for managing the sidebar's widgets
*/
if ( $is_registered_sidebar || $is_inactive_widgets ) { if ( $is_registered_sidebar || $is_inactive_widgets ) {
$setting_id = sprintf( 'sidebars_widgets[%s]', $sidebar_id ); $setting_id = sprintf( 'sidebars_widgets[%s]', $sidebar_id );
$setting_args = $this->get_setting_args( $setting_id ); $setting_args = $this->get_setting_args( $setting_id );
@ -350,9 +374,7 @@ final class WP_Customize_Widgets {
$this->manager->add_setting( $setting_id, $setting_args ); $this->manager->add_setting( $setting_id, $setting_args );
$new_setting_ids[] = $setting_id; $new_setting_ids[] = $setting_id;
/** // Add section to contain controls.
* Add section to contain controls
*/
$section_id = sprintf( 'sidebar-widgets-%s', $sidebar_id ); $section_id = sprintf( 'sidebar-widgets-%s', $sidebar_id );
if ( $is_active_sidebar ) { if ( $is_active_sidebar ) {
$section_args = array( $section_args = array(
@ -422,7 +444,7 @@ final class WP_Customize_Widgets {
} }
/** /**
* Covert a widget_id into its corresponding customizer setting id (option name) * Covert a widget_id into its corresponding customizer setting ID (option name).
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -440,12 +462,14 @@ final class WP_Customize_Widgets {
} }
/** /**
* Core widgets which may have controls wider than 250, but can still be * Determine whether the widget is considered "wide".
* 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 * Core widgets which may have controls wider than 250, but can
* customizer panel. This method will return all Core widgets as being * still be shown in the narrow customizer panel. The RSS and Text
* not wide, but this can be overridden with the is_wide_widget_in_customizer * widgets in Core, for example, have widths of 400 and yet they
* filter. * 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.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -468,8 +492,7 @@ final class WP_Customize_Widgets {
* @param bool $is_wide Whether the widget is wide, Default false. * @param bool $is_wide Whether the widget is wide, Default false.
* @param string $widget_id Widget ID. * @param string $widget_id Widget ID.
*/ */
$is_wide = apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id ); return apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id );
return $is_wide;
} }
/** /**
@ -503,7 +526,7 @@ final class WP_Customize_Widgets {
* @access public * @access public
* *
* @param string $setting_id Widget setting ID. * @param string $setting_id Widget setting ID.
* @return WP_Error|array Array contain a widget's id_base and number components, * @return WP_Error|array Array containing a widget's id_base and number components,
* or a WP_Error object. * or a WP_Error object.
*/ */
public function parse_widget_setting_id( $setting_id ) { public function parse_widget_setting_id( $setting_id ) {
@ -517,7 +540,7 @@ final class WP_Customize_Widgets {
} }
/** /**
* Enqueue scripts and styles for customizer panel and export data to JS. * Enqueue scripts and styles for customizer panel and export data to JavaScript.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -526,8 +549,10 @@ final class WP_Customize_Widgets {
wp_enqueue_style( 'customize-widgets' ); wp_enqueue_style( 'customize-widgets' );
wp_enqueue_script( 'customize-widgets' ); wp_enqueue_script( 'customize-widgets' );
// Export available widgets with control_tpl removed from model /*
// since plugins need templates to be in the DOM * Export available widgets with control_tpl removed from model
* since plugins need templates to be in the DOM.
*/
$available_widgets = array(); $available_widgets = array();
foreach ( $this->get_available_widgets() as $available_widget ) { foreach ( $this->get_available_widgets() as $available_widget ) {
unset( $available_widget['control_tpl'] ); unset( $available_widget['control_tpl'] );
@ -562,7 +587,10 @@ final class WP_Customize_Widgets {
' '
); );
// Why not wp_localize_script? Because we're not localizing, and it forces values into strings. /*
* Why not wp_localize_script? Because we're not localizing,
* and it forces values into strings.
*/
global $wp_scripts; global $wp_scripts;
$exports = array( $exports = array(
'nonce' => wp_create_nonce( 'update-widget' ), 'nonce' => wp_create_nonce( 'update-widget' ),
@ -594,7 +622,7 @@ final class WP_Customize_Widgets {
} }
/** /**
* Render the widget form control templates into the DOM so that plugin scripts can manipulate them * Render the widget form control templates into the DOM.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -618,7 +646,7 @@ final class WP_Customize_Widgets {
} }
/** /**
* Get common arguments to supply when constructing a customizer setting * Get common arguments to supply when constructing a Customizer setting.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -635,13 +663,24 @@ final class WP_Customize_Widgets {
'default' => array(), 'default' => array(),
); );
$args = array_merge( $args, $overrides ); $args = array_merge( $args, $overrides );
$args = apply_filters( 'widget_customizer_setting_args', $args, $id );
return $args; /**
* Filter the common arguments supplied when constructing a Customizer setting.
*
* @since 3.9.0
*
* @see WP_Customize_Setting
*
* @param array $args Array of Customizer setting arguments.
* @param string $id Widget setting ID.
*/
return apply_filters( 'widget_customizer_setting_args', $args, $id );
} }
/** /**
* Make sure that a sidebars_widgets[x] only ever consists of actual widget IDs. * Make sure that sidebar widget arrays only ever contain widget IDS.
* Used as sanitize_callback for each sidebars_widgets setting. *
* Used as the 'sanitize_callback' for each $sidebars_widgets setting.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -668,7 +707,8 @@ final class WP_Customize_Widgets {
* @access public * @access public
* *
* @see wp_list_widgets() * @see wp_list_widgets()
* @return array *
* @return array List of available widgets.
*/ */
public function get_available_widgets() { public function get_available_widgets() {
static $available_widgets = array(); static $available_widgets = array();
@ -726,7 +766,7 @@ final class WP_Customize_Widgets {
$list_widget_controls_args = wp_list_widget_controls_dynamic_sidebar( array( 0 => $args, 1 => $widget['params'][0] ) ); $list_widget_controls_args = wp_list_widget_controls_dynamic_sidebar( array( 0 => $args, 1 => $widget['params'][0] ) );
$control_tpl = $this->get_widget_control( $list_widget_controls_args ); $control_tpl = $this->get_widget_control( $list_widget_controls_args );
// The properties here are mapped to the Backbone Widget model // The properties here are mapped to the Backbone Widget model.
$available_widget = array_merge( $available_widget = array_merge(
$available_widget, $available_widget,
array( array(
@ -764,8 +804,7 @@ final class WP_Customize_Widgets {
} }
/** /**
* Invoke wp_widget_control() but capture the output buffer and transform the markup * Get the widget control markup.
* so that it can be used in the customizer.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -786,7 +825,7 @@ final class WP_Customize_Widgets {
} }
/** /**
* Add hooks for the customizer preview * Add hooks for the customizer preview.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -799,12 +838,13 @@ final class WP_Customize_Widgets {
} }
/** /**
* When previewing, make sure the proper previewing widgets are used.
* *
* * Because wp_get_sidebars_widgets() gets called early at init
* When previewing, make sure the proper previewing widgets are used. Because wp_get_sidebars_widgets() * (via wp_convert_widget_settings()) and can set global variable
* 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' )
* $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' ) before the customizer * before the customizer preview filter is added, we have to reset
* preview filter is added, we have to reset it after the filter has been added. * it after the filter has been added.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -813,12 +853,13 @@ final class WP_Customize_Widgets {
*/ */
public function preview_sidebars_widgets( $sidebars_widgets ) { public function preview_sidebars_widgets( $sidebars_widgets ) {
$sidebars_widgets = get_option( 'sidebars_widgets' ); $sidebars_widgets = get_option( 'sidebars_widgets' );
unset( $sidebars_widgets['array_version'] ); unset( $sidebars_widgets['array_version'] );
return $sidebars_widgets; return $sidebars_widgets;
} }
/** /**
* Enqueue scripts for the customizer preview * Enqueue scripts for the Customizer preview.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -851,7 +892,8 @@ final class WP_Customize_Widgets {
} }
/** /**
* At the very end of the page, at the very end of the wp_footer, communicate the sidebars that appeared on the page. * At the very end of the page, at the very end of the wp_footer,
* communicate the sidebars that appeared on the page.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -879,7 +921,7 @@ final class WP_Customize_Widgets {
} }
/** /**
* Keep track of the widgets that were rendered * Keep track of the widgets that were rendered.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -891,8 +933,12 @@ final class WP_Customize_Widgets {
} }
/** /**
* Keep track of the times that is_active_sidebar() is called in the template, and assume that this * Tally the sidebars rendered via is_active_sidebar().
* means that the sidebar would be rendered on the template if there were widgets populating it. *
* 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.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -904,14 +950,20 @@ final class WP_Customize_Widgets {
if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) { if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
$this->rendered_sidebars[] = $sidebar_id; $this->rendered_sidebars[] = $sidebar_id;
} }
// We may need to force this to true, and also force-true the value for dynamic_sidebar_has_widgets /*
// if we want to ensure that there is an area to drop widgets into, if the sidebar is empty. * We may need to force this to true, and also force-true the value
* for 'dynamic_sidebar_has_widgets' if we want to ensure that there
* is an area to drop widgets into, if the sidebar is empty.
*/
return $is_active; return $is_active;
} }
/** /**
* Keep track of the times that dynamic_sidebar() is called in the template, and assume that this * Tally the sidebars rendered via dynamic_sidebar().
* means that the sidebar would be rendered on the template if there were widgets populating it. *
* 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.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -923,9 +975,11 @@ final class WP_Customize_Widgets {
if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) { if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
$this->rendered_sidebars[] = $sidebar_id; $this->rendered_sidebars[] = $sidebar_id;
} }
/* /*
* We may need to force this to true, and also force-true the value for is_active_sidebar * We may need to force this to true, and also force-true the value
* if we want to ensure that there is an area to drop widgets into, if the sidebar is empty. * for 'is_active_sidebar' if we want to ensure there is an area to
* drop widgets into, if the sidebar is empty.
*/ */
return $has_widgets; return $has_widgets;
} }
@ -958,8 +1012,6 @@ final class WP_Customize_Widgets {
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
* *
* @see Widget_Customizer::sanitize_widget_js_instance()
*
* @param array $value Widget instance to sanitize. * @param array $value Widget instance to sanitize.
* @return array Sanitized widget instance. * @return array Sanitized widget instance.
*/ */
@ -997,8 +1049,6 @@ final class WP_Customize_Widgets {
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
* *
* @see Widget_Customizer::sanitize_widget_instance()
*
* @param array $value Widget instance to convert to JSON. * @param array $value Widget instance to convert to JSON.
* @return array JSON-converted widget instance. * @return array JSON-converted widget instance.
*/ */
@ -1016,8 +1066,10 @@ final class WP_Customize_Widgets {
} }
/** /**
* Strip out widget IDs for widgets which are no longer registered, such * Strip out widget IDs for widgets which are no longer registered.
* as the case when a plugin orphans a widget in a sidebar when it is deactivated. *
* One example where this might happen is when a plugin orphans a widget
* in a sidebar upon deactivation.
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
@ -1040,7 +1092,8 @@ final class WP_Customize_Widgets {
* @access public * @access public
* *
* @param string $widget_id Widget ID. * @param string $widget_id Widget ID.
* @return WP_Error|array Array containing the updated widget information. WP_Error, otherwise. * @return WP_Error|array Array containing the updated widget information.
* A WP_Error object, otherwise.
*/ */
public function call_widget_update( $widget_id ) { public function call_widget_update( $widget_id ) {
global $wp_registered_widget_updates, $wp_registered_widget_controls; global $wp_registered_widget_updates, $wp_registered_widget_controls;
@ -1132,16 +1185,19 @@ final class WP_Customize_Widgets {
} }
/** /**
* Allow customizer to update a widget using its form, but return the new * Update widget settings asynchronously.
*
* 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. * instance info via Ajax instead of saving it to the options table.
*
* Most code here copied from wp_ajax_save_widget() * Most code here copied from wp_ajax_save_widget()
* *
* @since 3.9.0 * @since 3.9.0
* @access public * @access public
* *
* @see wp_ajax_save_widget * @see wp_ajax_save_widget()
*
* @todo Reuse wp_ajax_save_widget now that we have option transactions? * @todo Reuse wp_ajax_save_widget now that we have option transactions?
* @action wp_ajax_update_widget
*/ */
public function wp_ajax_update_widget() { public function wp_ajax_update_widget() {
@ -1159,7 +1215,10 @@ final class WP_Customize_Widgets {
wp_send_json_error(); wp_send_json_error();
} }
/** This action is documented in wp-admin/includes/ajax-actions.php */
do_action( 'load-widgets.php' ); do_action( 'load-widgets.php' );
/** This action is documented in wp-admin/includes/ajax-actions.php */
do_action( 'widgets.php' ); do_action( 'widgets.php' );
/** This action is documented in wp-admin/widgets.php */ /** This action is documented in wp-admin/widgets.php */
@ -1189,41 +1248,65 @@ final class WP_Customize_Widgets {
***************************************************************************/ ***************************************************************************/
/** /**
* @var array $_captured_options values updated while capturing is happening * List of captured widget option updates.
*
* @since 3.9.0
* @access protected
* @var array $_captured_options Values updated while option capture is happening.
*/ */
protected $_captured_options = array(); protected $_captured_options = array();
/** /**
* @var bool $_is_current whether capturing is currently happening or not * Whether option capture is currently happening.
*
* @since 3.9.0
* @access protected
* @var bool $_is_current Whether option capture is currently happening or not.
*/ */
protected $_is_capturing_option_updates = false; protected $_is_capturing_option_updates = false;
/** /**
* @param $option_name * Determine whether the captured option update should be ignored.
* @return boolean *
* @since 3.9.0
* @access protected
*
* @param string $option_name Option name.
* @return boolean Whether the option capture is ignored.
*/ */
protected function is_option_capture_ignored( $option_name ) { protected function is_option_capture_ignored( $option_name ) {
return ( 0 === strpos( $option_name, '_transient_' ) ); return ( 0 === strpos( $option_name, '_transient_' ) );
} }
/** /**
* Get options updated * Retrieve captured widget option updates.
* @return array *
* @since 3.9.0
* @access protected
*
* @return array Array of captured options.
*/ */
protected function get_captured_options() { protected function get_captured_options() {
return $this->_captured_options; return $this->_captured_options;
} }
/** /**
* Get the number of options updated * Get the number of captured widget option updates.
* @return bool *
* @since 3.9.0
* @access protected
*
* @return int Number of updated options.
*/ */
protected function count_captured_options() { protected function count_captured_options() {
return count( $this->_captured_options ); return count( $this->_captured_options );
} }
/** /**
* Start keeping track of changes to options, and cache their new values * Start keeping track of changes to widget options, caching new values.
*
* @since 3.9.0
* @access protected
*/ */
protected function start_capturing_option_updates() { protected function start_capturing_option_updates() {
if ( $this->_is_capturing_option_updates ) { if ( $this->_is_capturing_option_updates ) {
@ -1235,13 +1318,15 @@ final class WP_Customize_Widgets {
} }
/** /**
* Pre-filter captured option values before updating.
*
* @access private * @access private
* @param mixed $new_value * @param mixed $new_value
* @param string $option_name * @param string $option_name
* @param mixed $old_value * @param mixed $old_value
* @return mixed * @return mixed
*/ */
public function _capture_filter_pre_update_option( $new_value, $option_name, $old_value ) { private function _capture_filter_pre_update_option( $new_value, $option_name, $old_value ) {
if ( $this->is_option_capture_ignored( $option_name ) ) { if ( $this->is_option_capture_ignored( $option_name ) ) {
return; return;
} }
@ -1256,11 +1341,13 @@ final class WP_Customize_Widgets {
} }
/** /**
* Pre-filter captured option values before retrieving.
*
* @access private * @access private
* @param mixed $value * @param mixed $value Option
* @return mixed * @return mixed
*/ */
public function _capture_filter_pre_get_option( $value ) { private function _capture_filter_pre_get_option( $value ) {
$option_name = preg_replace( '/^pre_option_/', '', current_filter() ); $option_name = preg_replace( '/^pre_option_/', '', current_filter() );
if ( isset( $this->_captured_options[$option_name] ) ) { if ( isset( $this->_captured_options[$option_name] ) ) {
$value = $this->_captured_options[$option_name]; $value = $this->_captured_options[$option_name];
@ -1271,7 +1358,10 @@ final class WP_Customize_Widgets {
} }
/** /**
* Undo any changes to the options since start_capturing_option_updates() was called * Undo any changes to the options since options capture began.
*
* @since 3.9.0
* @access protected
*/ */
protected function stop_capturing_option_updates() { protected function stop_capturing_option_updates() {
if ( ! $this->_is_capturing_option_updates ) { if ( ! $this->_is_capturing_option_updates ) {