<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[27903] trunk/src/wp-includes/class-wp-customize-widgets.php: Second-pass inline documentation improvements for WP_Customize_Widgets.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://core.trac.wordpress.org/changeset/27903">27903</a></dd>
<dt>Author</dt> <dd>DrewAPicture</dd>
<dt>Date</dt> <dd>2014-04-02 05:44:54 +0000 (Wed, 02 Apr 2014)</dd>
</dl>
<h3>Log Message</h3>
<pre>Second-pass inline documentation improvements for WP_Customize_Widgets.
See <a href="http://core.trac.wordpress.org/ticket/27534">#27534</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludesclasswpcustomizewidgetsphp">trunk/src/wp-includes/class-wp-customize-widgets.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludesclasswpcustomizewidgetsphp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/class-wp-customize-widgets.php (27902 => 27903)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/class-wp-customize-widgets.php 2014-04-02 03:01:31 UTC (rev 27902)
+++ trunk/src/wp-includes/class-wp-customize-widgets.php 2014-04-02 05:44:54 UTC (rev 27903)
</span><span class="lines">@@ -9,14 +9,18 @@
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> */
</span><span class="cx"> final class WP_Customize_Widgets {
</span><ins>+
</ins><span class="cx"> /**
</span><ins>+ * WP_Customize_Manager instance.
+ *
+ * @since 3.9.0
</ins><span class="cx"> * @access public
</span><span class="cx"> * @var WP_Customize_Manager
</span><span class="cx"> */
</span><span class="cx"> public $manager;
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * All id_bases for widgets defined in core
</del><ins>+ * All id_bases for widgets defined in core.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access protected
</span><span class="lines">@@ -71,6 +75,8 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><ins>+ *
+ * @param WP_Customize_Manager $manager Customize manager bootstrap instance.
</ins><span class="cx"> */
</span><span class="cx"> public function __construct( WP_Customize_Manager $manager ) {
</span><span class="cx"> $this->manager = $manager;
</span><span class="lines">@@ -107,15 +113,16 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ * Set up widget addition previews.
</ins><span class="cx"> *
</span><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * Since the widgets get registered (widgets_init) before the customizer settings are set up (customize_register),
- * we have to filter the options similarly to how the setting previewer will filter the options later.
- *
</del><span class="cx"> * @since 3.9.0
</span><span class="cx"> *
</span><span class="cx"> * @access public
</span><del>- * @global WP_Customize_Manager $wp_customize
</del><ins>+ * @global WP_Customize_Manager $wp_customize Customizer instance.
</ins><span class="cx"> */
</span><span class="cx"> public function setup_widget_addition_previews() {
</span><span class="cx"> $is_customize_preview = false;
</span><span class="lines">@@ -168,15 +175,20 @@
</span><span class="cx">
</span><span class="cx"> foreach ( $customized as $setting_id => $value ) {
</span><span class="cx"> if ( preg_match( '/^(widget_.+?)(\[(\d+)\])?$/', $setting_id, $matches ) ) {
</span><ins>+
+ /*
+ * @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 );
+ * };
+ */
</ins><span class="cx"> $body = sprintf( 'global $wp_customize; return $wp_customize->widgets->prepreview_added_widget_instance( $value, %s );', var_export( $setting_id, true ) );
</span><span class="cx"> $function = create_function( '$value', $body );
</span><del>- // @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 );
- //};
</del><span class="cx">
</span><del>- $option = $matches[1];
</del><ins>+ $option = $matches[1];
</ins><span class="cx">
</span><span class="cx"> $hook = sprintf( 'option_%s', $option );
</span><span class="cx"> add_filter( $hook, $function );
</span><span class="lines">@@ -186,9 +198,10 @@
</span><span class="cx"> add_filter( $hook, $function );
</span><span class="cx"> $this->_prepreview_added_filters[] = compact( 'hook', 'function' );
</span><span class="cx">
</span><del>- /**
- * Make sure the option is registered so that the update_option won't fail due to
- * the filters providing a default value, which causes the update_option() to get confused.
</del><ins>+ /*
+ * Make sure the option is registered so that the update_option()
+ * won't fail due to the filters providing a default value, which
+ * causes the update_option() to get confused.
</ins><span class="cx"> */
</span><span class="cx"> add_option( $option, array() );
</span><span class="cx"> }
</span><span class="lines">@@ -198,17 +211,17 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ * Ensure that newly-added widgets will appear in the widgets_sidebars.
</ins><span class="cx"> *
</span><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * 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.
- *
</del><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><del>- * @param array $sidebars_widgets Array of
- * @return array
</del><ins>+ * @param array $sidebars_widgets Associative array of sidebars and their widgets.
+ * @return array Filtered array of sidebars and their widgets.
</ins><span class="cx"> */
</span><span class="cx"> public function prepreview_added_sidebars_widgets( $sidebars_widgets ) {
</span><span class="cx"> foreach ( $this->_customized as $setting_id => $value ) {
</span><span class="lines">@@ -221,12 +234,13 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ * Ensure newly-added widgets have empty instances so they
+ * will be recognized.
</ins><span class="cx"> *
</span><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * Ensure that newly-added widgets will have empty instances so that they will be recognized.
- * 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.
- *
</del><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><span class="lines">@@ -239,7 +253,7 @@
</span><span class="cx"> $parsed_setting_id = $this->parse_widget_setting_id( $setting_id );
</span><span class="cx"> $widget_number = $parsed_setting_id['number'];
</span><span class="cx">
</span><del>- // Single widget
</del><ins>+ // Single widget.
</ins><span class="cx"> if ( is_null( $widget_number ) ) {
</span><span class="cx"> if ( false === $instance && empty( $value ) ) {
</span><span class="cx"> $instance = array();
</span><span class="lines">@@ -259,9 +273,12 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Remove filters added in setup_widget_addition_previews() which ensure that
- * widgets are populating the options during widgets_init
</del><ins>+ * Remove pre-preview filters.
</ins><span class="cx"> *
</span><ins>+ * Removes filters added in setup_widget_addition_previews()
+ * to ensure widgets are populating the options during
+ * 'widgets_init'.
+ *
</ins><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> */
</span><span class="lines">@@ -273,13 +290,18 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Make sure that all widgets get loaded into customizer; these actions are also done in the wp_ajax_save_widget()
</del><ins>+ * Make sure all widgets get loaded into the Customizer.
</ins><span class="cx"> *
</span><ins>+ * Note: these actions are also fired in wp_ajax_update_widget().
+ *
</ins><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> */
</span><span class="cx"> public function customize_controls_init() {
</span><ins>+ /** This action is documented in wp-admin/includes/ajax-actions.php */
</ins><span class="cx"> do_action( 'load-widgets.php' );
</span><ins>+
+ /** This action is documented in wp-admin/includes/ajax-actions.php */
</ins><span class="cx"> do_action( 'widgets.php' );
</span><span class="cx">
</span><span class="cx"> /** This action is documented in wp-admin/widgets.php */
</span><span class="lines">@@ -287,9 +309,12 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * When in preview, invoke customize_register for settings after WordPress is
- * loaded so that all filters have been initialized (e.g. Widget Visibility)
</del><ins>+ * Ensure widgets are available for all types of previews.
</ins><span class="cx"> *
</span><ins>+ * When in preview, hook to 'customize_register' for settings
+ * after WordPress is loaded so that all filters have been
+ * initialized (e.g. Widget Visibility).
+ *
</ins><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> */
</span><span class="lines">@@ -302,7 +327,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Register customizer settings and controls for all sidebars and widgets
</del><ins>+ * Register customizer settings and controls for all sidebars and widgets.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="lines">@@ -319,8 +344,9 @@
</span><span class="cx"> $new_setting_ids = array();
</span><span class="cx">
</span><span class="cx"> /*
</span><del>- * Register a setting for all widgets, including those which are active, inactive, and orphaned
- * since a widget may get suppressed from a sidebar via a plugin (like Widget Visibility).
</del><ins>+ * Register a setting for all widgets, including those which are active,
+ * inactive, and orphaned since a widget may get suppressed from a sidebar
+ * via a plugin (like Widget Visibility).
</ins><span class="cx"> */
</span><span class="cx"> foreach ( array_keys( $wp_registered_widgets ) as $widget_id ) {
</span><span class="cx"> $setting_id = $this->get_setting_id( $widget_id );
</span><span class="lines">@@ -339,9 +365,7 @@
</span><span class="cx"> $is_inactive_widgets = ( 'wp_inactive_widgets' === $sidebar_id );
</span><span class="cx"> $is_active_sidebar = ( $is_registered_sidebar && ! $is_inactive_widgets );
</span><span class="cx">
</span><del>- /**
- * Add setting for managing the sidebar's widgets
- */
</del><ins>+ // Add setting for managing the sidebar's widgets.
</ins><span class="cx"> if ( $is_registered_sidebar || $is_inactive_widgets ) {
</span><span class="cx"> $setting_id = sprintf( 'sidebars_widgets[%s]', $sidebar_id );
</span><span class="cx"> $setting_args = $this->get_setting_args( $setting_id );
</span><span class="lines">@@ -350,9 +374,7 @@
</span><span class="cx"> $this->manager->add_setting( $setting_id, $setting_args );
</span><span class="cx"> $new_setting_ids[] = $setting_id;
</span><span class="cx">
</span><del>- /**
- * Add section to contain controls
- */
</del><ins>+ // Add section to contain controls.
</ins><span class="cx"> $section_id = sprintf( 'sidebar-widgets-%s', $sidebar_id );
</span><span class="cx"> if ( $is_active_sidebar ) {
</span><span class="cx"> $section_args = array(
</span><span class="lines">@@ -422,7 +444,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Covert a widget_id into its corresponding customizer setting id (option name)
</del><ins>+ * Covert a widget_id into its corresponding customizer setting ID (option name).
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="lines">@@ -440,13 +462,15 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * 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.
</del><ins>+ * Determine whether the widget is considered "wide".
</ins><span class="cx"> *
</span><ins>+ * 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.
+ *
</ins><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><span class="lines">@@ -468,8 +492,7 @@
</span><span class="cx"> * @param bool $is_wide Whether the widget is wide, Default false.
</span><span class="cx"> * @param string $widget_id Widget ID.
</span><span class="cx"> */
</span><del>- $is_wide = apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id );
- return $is_wide;
</del><ins>+ return apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><span class="lines">@@ -503,7 +526,7 @@
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><span class="cx"> * @param string $setting_id Widget setting ID.
</span><del>- * @return WP_Error|array Array contain a widget's id_base and number components,
</del><ins>+ * @return WP_Error|array Array containing a widget's id_base and number components,
</ins><span class="cx"> * or a WP_Error object.
</span><span class="cx"> */
</span><span class="cx"> public function parse_widget_setting_id( $setting_id ) {
</span><span class="lines">@@ -517,7 +540,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Enqueue scripts and styles for customizer panel and export data to JS.
</del><ins>+ * Enqueue scripts and styles for customizer panel and export data to JavaScript.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="lines">@@ -526,8 +549,10 @@
</span><span class="cx"> wp_enqueue_style( 'customize-widgets' );
</span><span class="cx"> wp_enqueue_script( 'customize-widgets' );
</span><span class="cx">
</span><del>- // Export available widgets with control_tpl removed from model
- // since plugins need templates to be in the DOM
</del><ins>+ /*
+ * Export available widgets with control_tpl removed from model
+ * since plugins need templates to be in the DOM.
+ */
</ins><span class="cx"> $available_widgets = array();
</span><span class="cx"> foreach ( $this->get_available_widgets() as $available_widget ) {
</span><span class="cx"> unset( $available_widget['control_tpl'] );
</span><span class="lines">@@ -562,7 +587,10 @@
</span><span class="cx"> '
</span><span class="cx"> );
</span><span class="cx">
</span><del>- // Why not wp_localize_script? Because we're not localizing, and it forces values into strings.
</del><ins>+ /*
+ * Why not wp_localize_script? Because we're not localizing,
+ * and it forces values into strings.
+ */
</ins><span class="cx"> global $wp_scripts;
</span><span class="cx"> $exports = array(
</span><span class="cx"> 'nonce' => wp_create_nonce( 'update-widget' ),
</span><span class="lines">@@ -594,7 +622,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Render the widget form control templates into the DOM so that plugin scripts can manipulate them
</del><ins>+ * Render the widget form control templates into the DOM.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="lines">@@ -618,7 +646,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Get common arguments to supply when constructing a customizer setting
</del><ins>+ * Get common arguments to supply when constructing a Customizer setting.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="lines">@@ -635,14 +663,25 @@
</span><span class="cx"> 'default' => array(),
</span><span class="cx"> );
</span><span class="cx"> $args = array_merge( $args, $overrides );
</span><del>- $args = apply_filters( 'widget_customizer_setting_args', $args, $id );
- return $args;
</del><ins>+
+ /**
+ * 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 );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Make sure that a sidebars_widgets[x] only ever consists of actual widget IDs.
- * Used as sanitize_callback for each sidebars_widgets setting.
</del><ins>+ * Make sure that sidebar widget arrays only ever contain widget IDS.
</ins><span class="cx"> *
</span><ins>+ * Used as the 'sanitize_callback' for each $sidebars_widgets setting.
+ *
</ins><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><span class="lines">@@ -668,7 +707,8 @@
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><span class="cx"> * @see wp_list_widgets()
</span><del>- * @return array
</del><ins>+ *
+ * @return array List of available widgets.
</ins><span class="cx"> */
</span><span class="cx"> public function get_available_widgets() {
</span><span class="cx"> static $available_widgets = array();
</span><span class="lines">@@ -726,7 +766,7 @@
</span><span class="cx"> $list_widget_controls_args = wp_list_widget_controls_dynamic_sidebar( array( 0 => $args, 1 => $widget['params'][0] ) );
</span><span class="cx"> $control_tpl = $this->get_widget_control( $list_widget_controls_args );
</span><span class="cx">
</span><del>- // The properties here are mapped to the Backbone Widget model
</del><ins>+ // The properties here are mapped to the Backbone Widget model.
</ins><span class="cx"> $available_widget = array_merge(
</span><span class="cx"> $available_widget,
</span><span class="cx"> array(
</span><span class="lines">@@ -764,8 +804,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Invoke wp_widget_control() but capture the output buffer and transform the markup
- * so that it can be used in the customizer.
</del><ins>+ * Get the widget control markup.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="lines">@@ -786,7 +825,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Add hooks for the customizer preview
</del><ins>+ * Add hooks for the customizer preview.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="lines">@@ -799,13 +838,14 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ * When previewing, make sure the proper previewing widgets are used.
</ins><span class="cx"> *
</span><ins>+ * 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, we have to reset
+ * it after the filter has been added.
</ins><span class="cx"> *
</span><del>- * When previewing, make sure the proper previewing widgets are used. 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, we have to reset it after the filter has been added.
- *
</del><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><span class="lines">@@ -813,12 +853,13 @@
</span><span class="cx"> */
</span><span class="cx"> public function preview_sidebars_widgets( $sidebars_widgets ) {
</span><span class="cx"> $sidebars_widgets = get_option( 'sidebars_widgets' );
</span><ins>+
</ins><span class="cx"> unset( $sidebars_widgets['array_version'] );
</span><span class="cx"> return $sidebars_widgets;
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Enqueue scripts for the customizer preview
</del><ins>+ * Enqueue scripts for the Customizer preview.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="lines">@@ -851,7 +892,8 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * At the very end of the page, at the very end of the wp_footer, communicate the sidebars that appeared on the page.
</del><ins>+ * At the very end of the page, at the very end of the wp_footer,
+ * communicate the sidebars that appeared on the page.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="lines">@@ -879,7 +921,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Keep track of the widgets that were rendered
</del><ins>+ * Keep track of the widgets that were rendered.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="lines">@@ -891,9 +933,13 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * 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.
</del><ins>+ * Tally the sidebars rendered via is_active_sidebar().
</ins><span class="cx"> *
</span><ins>+ * 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.
+ *
</ins><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><span class="lines">@@ -904,15 +950,21 @@
</span><span class="cx"> if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
</span><span class="cx"> $this->rendered_sidebars[] = $sidebar_id;
</span><span class="cx"> }
</span><del>- // 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.
</del><ins>+ /*
+ * 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.
+ */
</ins><span class="cx"> return $is_active;
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Keep track of the times that dynamic_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.
</del><ins>+ * Tally the sidebars rendered via dynamic_sidebar().
</ins><span class="cx"> *
</span><ins>+ * 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.
+ *
</ins><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><span class="lines">@@ -923,9 +975,11 @@
</span><span class="cx"> if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
</span><span class="cx"> $this->rendered_sidebars[] = $sidebar_id;
</span><span class="cx"> }
</span><ins>+
</ins><span class="cx"> /*
</span><del>- * We may need to force this to true, and also force-true the value for is_active_sidebar
- * if we want to ensure that there is an area to drop widgets into, if the sidebar is empty.
</del><ins>+ * We may need to force this to true, and also force-true the value
+ * for 'is_active_sidebar' if we want to ensure there is an area to
+ * drop widgets into, if the sidebar is empty.
</ins><span class="cx"> */
</span><span class="cx"> return $has_widgets;
</span><span class="cx"> }
</span><span class="lines">@@ -958,8 +1012,6 @@
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><del>- * @see Widget_Customizer::sanitize_widget_js_instance()
- *
</del><span class="cx"> * @param array $value Widget instance to sanitize.
</span><span class="cx"> * @return array Sanitized widget instance.
</span><span class="cx"> */
</span><span class="lines">@@ -997,8 +1049,6 @@
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><del>- * @see Widget_Customizer::sanitize_widget_instance()
- *
</del><span class="cx"> * @param array $value Widget instance to convert to JSON.
</span><span class="cx"> * @return array JSON-converted widget instance.
</span><span class="cx"> */
</span><span class="lines">@@ -1016,9 +1066,11 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Strip out widget IDs for widgets which are no longer registered, such
- * as the case when a plugin orphans a widget in a sidebar when it is deactivated.
</del><ins>+ * Strip out widget IDs for widgets which are no longer registered.
</ins><span class="cx"> *
</span><ins>+ * One example where this might happen is when a plugin orphans a widget
+ * in a sidebar upon deactivation.
+ *
</ins><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><span class="lines">@@ -1040,7 +1092,8 @@
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><span class="cx"> * @param string $widget_id Widget ID.
</span><del>- * @return WP_Error|array Array containing the updated widget information. WP_Error, otherwise.
</del><ins>+ * @return WP_Error|array Array containing the updated widget information.
+ * A WP_Error object, otherwise.
</ins><span class="cx"> */
</span><span class="cx"> public function call_widget_update( $widget_id ) {
</span><span class="cx"> global $wp_registered_widget_updates, $wp_registered_widget_controls;
</span><span class="lines">@@ -1132,16 +1185,19 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Allow customizer to update a widget using its form, but return the new
</del><ins>+ * Update widget settings asynchronously.
+ *
+ * Allows the Customizer to update a widget using its form, but return the new
</ins><span class="cx"> * instance info via Ajax instead of saving it to the options table.
</span><ins>+ *
</ins><span class="cx"> * Most code here copied from wp_ajax_save_widget()
</span><span class="cx"> *
</span><span class="cx"> * @since 3.9.0
</span><span class="cx"> * @access public
</span><span class="cx"> *
</span><del>- * @see wp_ajax_save_widget
</del><ins>+ * @see wp_ajax_save_widget()
+ *
</ins><span class="cx"> * @todo Reuse wp_ajax_save_widget now that we have option transactions?
</span><del>- * @action wp_ajax_update_widget
</del><span class="cx"> */
</span><span class="cx"> public function wp_ajax_update_widget() {
</span><span class="cx">
</span><span class="lines">@@ -1159,7 +1215,10 @@
</span><span class="cx"> wp_send_json_error();
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+ /** This action is documented in wp-admin/includes/ajax-actions.php */
</ins><span class="cx"> do_action( 'load-widgets.php' );
</span><ins>+
+ /** This action is documented in wp-admin/includes/ajax-actions.php */
</ins><span class="cx"> do_action( 'widgets.php' );
</span><span class="cx">
</span><span class="cx"> /** This action is documented in wp-admin/widgets.php */
</span><span class="lines">@@ -1189,41 +1248,65 @@
</span><span class="cx"> ***************************************************************************/
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * @var array $_captured_options values updated while capturing is happening
</del><ins>+ * List of captured widget option updates.
+ *
+ * @since 3.9.0
+ * @access protected
+ * @var array $_captured_options Values updated while option capture is happening.
</ins><span class="cx"> */
</span><span class="cx"> protected $_captured_options = array();
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * @var bool $_is_current whether capturing is currently happening or not
</del><ins>+ * Whether option capture is currently happening.
+ *
+ * @since 3.9.0
+ * @access protected
+ * @var bool $_is_current Whether option capture is currently happening or not.
</ins><span class="cx"> */
</span><span class="cx"> protected $_is_capturing_option_updates = false;
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * @param $option_name
- * @return boolean
</del><ins>+ * Determine whether the captured option update should be ignored.
+ *
+ * @since 3.9.0
+ * @access protected
+ *
+ * @param string $option_name Option name.
+ * @return boolean Whether the option capture is ignored.
</ins><span class="cx"> */
</span><span class="cx"> protected function is_option_capture_ignored( $option_name ) {
</span><span class="cx"> return ( 0 === strpos( $option_name, '_transient_' ) );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Get options updated
- * @return array
</del><ins>+ * Retrieve captured widget option updates.
+ *
+ * @since 3.9.0
+ * @access protected
+ *
+ * @return array Array of captured options.
</ins><span class="cx"> */
</span><span class="cx"> protected function get_captured_options() {
</span><span class="cx"> return $this->_captured_options;
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Get the number of options updated
- * @return bool
</del><ins>+ * Get the number of captured widget option updates.
+ *
+ * @since 3.9.0
+ * @access protected
+ *
+ * @return int Number of updated options.
</ins><span class="cx"> */
</span><span class="cx"> protected function count_captured_options() {
</span><span class="cx"> return count( $this->_captured_options );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Start keeping track of changes to options, and cache their new values
</del><ins>+ * Start keeping track of changes to widget options, caching new values.
+ *
+ * @since 3.9.0
+ * @access protected
</ins><span class="cx"> */
</span><span class="cx"> protected function start_capturing_option_updates() {
</span><span class="cx"> if ( $this->_is_capturing_option_updates ) {
</span><span class="lines">@@ -1235,13 +1318,15 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ * Pre-filter captured option values before updating.
+ *
</ins><span class="cx"> * @access private
</span><span class="cx"> * @param mixed $new_value
</span><span class="cx"> * @param string $option_name
</span><span class="cx"> * @param mixed $old_value
</span><span class="cx"> * @return mixed
</span><span class="cx"> */
</span><del>- public function _capture_filter_pre_update_option( $new_value, $option_name, $old_value ) {
</del><ins>+ private function _capture_filter_pre_update_option( $new_value, $option_name, $old_value ) {
</ins><span class="cx"> if ( $this->is_option_capture_ignored( $option_name ) ) {
</span><span class="cx"> return;
</span><span class="cx"> }
</span><span class="lines">@@ -1256,11 +1341,13 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ * Pre-filter captured option values before retrieving.
+ *
</ins><span class="cx"> * @access private
</span><del>- * @param mixed $value
</del><ins>+ * @param mixed $value Option
</ins><span class="cx"> * @return mixed
</span><span class="cx"> */
</span><del>- public function _capture_filter_pre_get_option( $value ) {
</del><ins>+ private function _capture_filter_pre_get_option( $value ) {
</ins><span class="cx"> $option_name = preg_replace( '/^pre_option_/', '', current_filter() );
</span><span class="cx"> if ( isset( $this->_captured_options[$option_name] ) ) {
</span><span class="cx"> $value = $this->_captured_options[$option_name];
</span><span class="lines">@@ -1271,7 +1358,10 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Undo any changes to the options since start_capturing_option_updates() was called
</del><ins>+ * Undo any changes to the options since options capture began.
+ *
+ * @since 3.9.0
+ * @access protected
</ins><span class="cx"> */
</span><span class="cx"> protected function stop_capturing_option_updates() {
</span><span class="cx"> if ( ! $this->_is_capturing_option_updates ) {
</span></span></pre>
</div>
</div>
</body>
</html>