<!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>[27753] trunk/src/wp-includes/class-wp-customize-widgets.php: Widget Customizer: First pass for inline docs.</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/27753">27753</a></dd>
<dt>Author</dt> <dd>ocean90</dd>
<dt>Date</dt> <dd>2014-03-26 22:28:49 +0000 (Wed, 26 Mar 2014)</dd>
</dl>
<h3>Log Message</h3>
<pre>Widget Customizer: First pass for inline docs.
props DrewAPicture.
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 (27752 => 27753)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/class-wp-customize-widgets.php 2014-03-26 22:23:52 UTC (rev 27752)
+++ trunk/src/wp-includes/class-wp-customize-widgets.php 2014-03-26 22:28:49 UTC (rev 27753)
</span><span class="lines">@@ -1,6 +1,12 @@
</span><span class="cx"> <?php
</span><span class="cx"> /**
</span><del>- * Widget customizer manager class.
</del><ins>+ * Customize Widgets Class
+ *
+ * Implements widget management in the Customizer.
+ *
+ * @since 3.9.0
+ * @package WordPress
+ * @subpackage Customize
</ins><span class="cx"> */
</span><span class="cx"> class WP_Customize_Widgets {
</span><span class="cx"> const UPDATE_WIDGET_AJAX_ACTION = 'update-widget';
</span><span class="lines">@@ -9,6 +15,9 @@
</span><span class="cx"> /**
</span><span class="cx"> * All id_bases for widgets defined in core
</span><span class="cx"> *
</span><ins>+ * @since 3.9.0
+ * @static
+ * @access protected
</ins><span class="cx"> * @var array
</span><span class="cx"> */
</span><span class="cx"> protected static $core_widget_id_bases = array(
</span><span class="lines">@@ -28,43 +37,87 @@
</span><span class="cx"> );
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ * @since 3.9.0
+ * @static
+ * @access protected
+ * @var
+ */
+ protected static $_customized;
+
+ /**
+ * @since 3.9.0
+ * @static
+ * @access protected
+ * @var array
+ */
+ protected static $_prepreview_added_filters = array();
+
+ /**
+ * @since 3.9.0
+ * @static
+ * @access protected
+ * @var array
+ */
+ static protected $rendered_sidebars = array();
+
+ /**
+ * @since 3.9.0
+ * @static
+ * @access protected
+ * @var array
+ */
+ static protected $rendered_widgets = array();
+
+ /**
</ins><span class="cx"> * Initial loader.
</span><ins>+ *
+ * @since 3.9.0
+ * @static
+ * @access public
</ins><span class="cx"> */
</span><span class="cx"> static function setup() {
</span><del>- add_action( 'after_setup_theme', array( __CLASS__, 'setup_widget_addition_previews' ) );
- add_action( 'customize_controls_init', array( __CLASS__, 'customize_controls_init' ) );
- add_action( 'customize_register', array( __CLASS__, 'schedule_customize_register' ), 1 );
- add_action( 'customize_controls_enqueue_scripts', array( __CLASS__, 'customize_controls_enqueue_deps' ) );
</del><ins>+ add_action( 'after_setup_theme', array( __CLASS__, 'setup_widget_addition_previews' ) );
+ add_action( 'customize_controls_init', array( __CLASS__, 'customize_controls_init' ) );
+ add_action( 'customize_register', array( __CLASS__, 'schedule_customize_register' ), 1 );
+ add_action( 'customize_controls_enqueue_scripts', array( __CLASS__, 'customize_controls_enqueue_deps' ) );
</ins><span class="cx"> add_action( 'customize_controls_print_footer_scripts', array( __CLASS__, 'output_widget_control_templates' ) );
</span><del>- add_action( 'customize_preview_init', array( __CLASS__, 'customize_preview_init' ) );
</del><ins>+ add_action( 'customize_preview_init', array( __CLASS__, 'customize_preview_init' ) );
</ins><span class="cx">
</span><del>- add_action( 'dynamic_sidebar', array( __CLASS__, 'tally_rendered_widgets' ) );
- add_filter( 'is_active_sidebar', array( __CLASS__, 'tally_sidebars_via_is_active_sidebar_calls' ), 10, 2 );
- add_filter( 'dynamic_sidebar_has_widgets', array( __CLASS__, 'tally_sidebars_via_dynamic_sidebar_calls' ), 10, 2 );
</del><ins>+ add_action( 'dynamic_sidebar', array( __CLASS__, 'tally_rendered_widgets' ) );
+ add_filter( 'is_active_sidebar', array( __CLASS__, 'tally_sidebars_via_is_active_sidebar_calls' ), 10, 2 );
+ add_filter( 'dynamic_sidebar_has_widgets', array( __CLASS__, 'tally_sidebars_via_dynamic_sidebar_calls' ), 10, 2 );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Get an unslashed post value, or return a default
</del><ins>+ * Get an unslashed post value or return a default.
</ins><span class="cx"> *
</span><del>- * @param string $name
- * @param mixed $default
- * @return mixed
</del><ins>+ * @since 3.9.0
+ *
+ * @static
+ * @access public
+ *
+ * @param string $name Post value.
+ * @param mixed $default Default post value.
+ * @return mixed Unslashed post value or default value.
</ins><span class="cx"> */
</span><span class="cx"> static function get_post_value( $name, $default = null ) {
</span><del>- if ( ! isset( $_POST[$name] ) ) {
</del><ins>+ if ( ! isset( $_POST[ $name ] ) ) {
</ins><span class="cx"> return $default;
</span><span class="cx"> }
</span><span class="cx"> return wp_unslash( $_POST[$name] );
</span><span class="cx"> }
</span><span class="cx">
</span><del>- protected static $_customized;
- protected static $_prepreview_added_filters = array();
-
</del><span class="cx"> /**
</span><ins>+ *
+ *
</ins><span class="cx"> * Since the widgets get registered (widgets_init) before the customizer settings are set up (customize_register),
</span><span class="cx"> * we have to filter the options similarly to how the setting previewer will filter the options later.
</span><span class="cx"> *
</span><del>- * @action after_setup_theme
</del><ins>+ * @since 3.9.0
+ *
+ * @static
+ * @access public
+ * @global WP_Customize_Manager $wp_customize
</ins><span class="cx"> */
</span><span class="cx"> static function setup_widget_addition_previews() {
</span><span class="cx"> global $wp_customize;
</span><span class="lines">@@ -99,11 +152,12 @@
</span><span class="cx"> return;
</span><span class="cx"> }
</span><span class="cx">
</span><del>- // Input from customizer preview
</del><ins>+ // Input from customizer preview.
</ins><span class="cx"> if ( isset( $_POST['customized'] ) ) {
</span><span class="cx"> $customized = json_decode( self::get_post_value( 'customized' ), true );
</span><span class="cx"> }
</span><del>- // Input from ajax widget update request
</del><ins>+
+ // Input from ajax widget update request.
</ins><span class="cx"> else {
</span><span class="cx"> $customized = array();
</span><span class="cx"> $id_base = self::get_post_value( 'id_base' );
</span><span class="lines">@@ -152,11 +206,17 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ *
+ *
</ins><span class="cx"> * Ensure that newly-added widgets will appear in the widgets_sidebars.
</span><span class="cx"> * This is necessary because the customizer's setting preview filters are added after the widgets_init action,
</span><span class="cx"> * which is too late for the widgets to be set up properly.
</span><span class="cx"> *
</span><del>- * @param array $sidebars_widgets
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param array $sidebars_widgets Array of
</ins><span class="cx"> * @return array
</span><span class="cx"> */
</span><span class="cx"> static function prepreview_added_sidebars_widgets( $sidebars_widgets ) {
</span><span class="lines">@@ -170,13 +230,19 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ *
+ *
</ins><span class="cx"> * Ensure that newly-added widgets will have empty instances so that they will be recognized.
</span><span class="cx"> * This is necessary because the customizer's setting preview filters are added after the widgets_init action,
</span><span class="cx"> * which is too late for the widgets to be set up properly.
</span><span class="cx"> *
</span><del>- * @param array $instance
- * @param string $setting_id
- * @return array
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param array $instance Widget instance.
+ * @param string $setting_id Widget setting ID.
+ * @return array Parsed widget instance.
</ins><span class="cx"> */
</span><span class="cx"> static function prepreview_added_widget_instance( $instance, $setting_id ) {
</span><span class="cx"> if ( isset( self::$_customized[$setting_id] ) ) {
</span><span class="lines">@@ -206,7 +272,9 @@
</span><span class="cx"> * Remove filters added in setup_widget_addition_previews() which ensure that
</span><span class="cx"> * widgets are populating the options during widgets_init
</span><span class="cx"> *
</span><del>- * @action wp_loaded
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
</ins><span class="cx"> */
</span><span class="cx"> static function remove_prepreview_filters() {
</span><span class="cx"> foreach ( self::$_prepreview_added_filters as $prepreview_added_filter ) {
</span><span class="lines">@@ -218,8 +286,9 @@
</span><span class="cx"> /**
</span><span class="cx"> * Make sure that all widgets get loaded into customizer; these actions are also done in the wp_ajax_save_widget()
</span><span class="cx"> *
</span><del>- * @see wp_ajax_save_widget()
- * @action customize_controls_init
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
</ins><span class="cx"> */
</span><span class="cx"> static function customize_controls_init() {
</span><span class="cx"> do_action( 'load-widgets.php' );
</span><span class="lines">@@ -230,6 +299,12 @@
</span><span class="cx"> /**
</span><span class="cx"> * When in preview, invoke customize_register for settings after WordPress is
</span><span class="cx"> * loaded so that all filters have been initialized (e.g. Widget Visibility)
</span><ins>+ *
+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param WP_Customize_Manager $wp_customize Customizer instance.
</ins><span class="cx"> */
</span><span class="cx"> static function schedule_customize_register( $wp_customize ) {
</span><span class="cx"> if ( is_admin() ) { // @todo for some reason, $wp_customize->is_preview() is true here?
</span><span class="lines">@@ -242,7 +317,11 @@
</span><span class="cx"> /**
</span><span class="cx"> * Register customizer settings and controls for all sidebars and widgets
</span><span class="cx"> *
</span><del>- * @action customize_register
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param WP_Customize_Manager $wp_customize Customizer instance.
</ins><span class="cx"> */
</span><span class="cx"> static function customize_register( $wp_customize = null ) {
</span><span class="cx"> global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_sidebars;
</span><span class="lines">@@ -258,7 +337,7 @@
</span><span class="cx">
</span><span class="cx"> $new_setting_ids = array();
</span><span class="cx">
</span><del>- /**
</del><ins>+ /*
</ins><span class="cx"> * Register a setting for all widgets, including those which are active, inactive, and orphaned
</span><span class="cx"> * since a widget may get suppressed from a sidebar via a plugin (like Widget Visibility).
</span><span class="cx"> */
</span><span class="lines">@@ -318,11 +397,10 @@
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="cx">
</span><del>- /**
- * Add a control for each active widget (located in a sidebar)
- */
</del><ins>+ // Add a control for each active widget (located in a sidebar).
</ins><span class="cx"> foreach ( $sidebar_widget_ids as $i => $widget_id ) {
</span><del>- // Skip widgets that may have gone away due to a plugin being deactivated
</del><ins>+
+ // Skip widgets that may have gone away due to a plugin being deactivated.
</ins><span class="cx"> if ( ! $is_active_sidebar || ! isset( $GLOBALS['wp_registered_widgets'][$widget_id] ) ) {
</span><span class="cx"> continue;
</span><span class="cx"> }
</span><span class="lines">@@ -349,10 +427,9 @@
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="cx">
</span><del>- /**
- * We have to register these settings later than customize_preview_init so that other
- * filters have had a chance to run.
- * @see self::schedule_customize_register()
</del><ins>+ /*
+ * We have to register these settings later than customize_preview_init
+ * so that other filters have had a chance to run.
</ins><span class="cx"> */
</span><span class="cx"> if ( did_action( 'customize_preview_init' ) ) {
</span><span class="cx"> foreach ( $new_setting_ids as $new_setting_id ) {
</span><span class="lines">@@ -366,9 +443,12 @@
</span><span class="cx"> /**
</span><span class="cx"> * Covert a widget_id into its corresponding customizer setting id (option name)
</span><span class="cx"> *
</span><del>- * @param string $widget_id
- * @see _get_widget_id_base()
- * @return string
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param string $widget_id Widget ID.
+ * @return string Maybe-parsed widget ID.
</ins><span class="cx"> */
</span><span class="cx"> static function get_setting_id( $widget_id ) {
</span><span class="cx"> $parsed_widget_id = self::parse_widget_id( $widget_id );
</span><span class="lines">@@ -387,8 +467,12 @@
</span><span class="cx"> * not wide, but this can be overridden with the is_wide_widget_in_customizer
</span><span class="cx"> * filter.
</span><span class="cx"> *
</span><del>- * @param string $widget_id
- * @return bool
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param string $widget_id Widget ID.
+ * @return bool Whether or not the widget is a "wide" widget.
</ins><span class="cx"> */
</span><span class="cx"> static function is_wide_widget( $widget_id ) {
</span><span class="cx"> global $wp_registered_widget_controls;
</span><span class="lines">@@ -396,15 +480,28 @@
</span><span class="cx"> $width = $wp_registered_widget_controls[$widget_id]['width'];
</span><span class="cx"> $is_core = in_array( $parsed_widget_id['id_base'], self::$core_widget_id_bases );
</span><span class="cx"> $is_wide = ( $width > 250 && ! $is_core );
</span><ins>+
+ /**
+ * Filter whether the given widget is considered "wide".
+ *
+ * @since 3.9.0
+ *
+ * @param bool $is_wide Whether the widget is wide, Default false.
+ * @param string $widget_id Widget ID.
+ */
</ins><span class="cx"> $is_wide = apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id );
</span><span class="cx"> return $is_wide;
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Covert a widget ID into its id_base and number components
</del><ins>+ * Covert a widget ID into its id_base and number components.
</ins><span class="cx"> *
</span><del>- * @param string $widget_id
- * @return array
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param string $widget_id Widget ID.
+ * @return array Array containing a widget's id_base and number components.
</ins><span class="cx"> */
</span><span class="cx"> static function parse_widget_id( $widget_id ) {
</span><span class="cx"> $parsed = array(
</span><span class="lines">@@ -422,10 +519,15 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Convert a widget setting ID (option path) to its id_base and number components
</del><ins>+ * Convert a widget setting ID (option path) to its id_base and number components.
</ins><span class="cx"> *
</span><del>- * @param string $setting_id
- * @return WP_Error|array
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param string $setting_id Widget setting ID.
+ * @return WP_Error|array Array contain a widget's id_base and number components,
+ * or a WP_Error object.
</ins><span class="cx"> */
</span><span class="cx"> static function parse_widget_setting_id( $setting_id ) {
</span><span class="cx"> if ( ! preg_match( '/^(widget_(.+?))(?:\[(\d+)\])?$/', $setting_id, $matches ) ) {
</span><span class="lines">@@ -438,9 +540,11 @@
</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 JS.
</ins><span class="cx"> *
</span><del>- * @action customize_controls_enqueue_scripts
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
</ins><span class="cx"> */
</span><span class="cx"> static function customize_controls_enqueue_deps() {
</span><span class="cx"> wp_enqueue_style( 'customize-widgets' );
</span><span class="lines">@@ -482,7 +586,7 @@
</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"> 'update_widget_ajax_action' => self::UPDATE_WIDGET_AJAX_ACTION,
</span><span class="lines">@@ -518,7 +622,9 @@
</span><span class="cx"> /**
</span><span class="cx"> * Render the widget form control templates into the DOM so that plugin scripts can manipulate them
</span><span class="cx"> *
</span><del>- * @action customize_controls_print_footer_scripts
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
</ins><span class="cx"> */
</span><span class="cx"> static function output_widget_control_templates() {
</span><span class="cx"> ?>
</span><span class="lines">@@ -540,9 +646,13 @@
</span><span class="cx"> /**
</span><span class="cx"> * Get common arguments to supply when constructing a customizer setting
</span><span class="cx"> *
</span><del>- * @param string $id
- * @param array [$overrides]
- * @return array
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param string $id Widget setting ID.
+ * @param array $overrides Array of setting overrides.
+ * @return array Possibly modified setting arguments.
</ins><span class="cx"> */
</span><span class="cx"> static function get_setting_args( $id, $overrides = array() ) {
</span><span class="cx"> $args = array(
</span><span class="lines">@@ -560,8 +670,12 @@
</span><span class="cx"> * Make sure that a sidebars_widgets[x] only ever consists of actual widget IDs.
</span><span class="cx"> * Used as sanitize_callback for each sidebars_widgets setting.
</span><span class="cx"> *
</span><del>- * @param array $widget_ids
- * @return array
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param array $widget_ids Array of widget IDs.
+ * @return array Array of sanitized widget IDs.
</ins><span class="cx"> */
</span><span class="cx"> static function sanitize_sidebar_widgets( $widget_ids ) {
</span><span class="cx"> global $wp_registered_widgets;
</span><span class="lines">@@ -576,8 +690,12 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Build up an index of all available widgets for use in Backbone models
</del><ins>+ * Build up an index of all available widgets for use in Backbone models.
</ins><span class="cx"> *
</span><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
</ins><span class="cx"> * @see wp_list_widgets()
</span><span class="cx"> * @return array
</span><span class="cx"> */
</span><span class="lines">@@ -660,22 +778,30 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Replace with inline closure once on PHP 5.3:
- * sort( $array, function ( $a, $b ) { return strnatcasecmp( $a['name'], $b['name'] ); } );
</del><ins>+ * Naturally order available widgets by name.
</ins><span class="cx"> *
</span><del>- * @access private
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param array $widget_a The first widget to compare.
+ * @param array $widget_b The second widget to compare.
+ * @return int Reorder position for the current widget comparison.
</ins><span class="cx"> */
</span><del>- static function _sort_name_callback( $a, $b ) {
- return strnatcasecmp( $a['name'], $b['name'] );
</del><ins>+ static function _sort_name_callback( $widget_a, $widget_b ) {
+ return strnatcasecmp( $widget_a['name'], $widget_b['name'] );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><span class="cx"> * Invoke wp_widget_control() but capture the output buffer and transform the markup
</span><span class="cx"> * so that it can be used in the customizer.
</span><span class="cx"> *
</span><del>- * @see wp_widget_control()
- * @param array $args
- * @return string
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param array $args Widget control arguments.
+ * @return string Widget control form HTML markup.
</ins><span class="cx"> */
</span><span class="cx"> static function get_widget_control( $args ) {
</span><span class="cx"> ob_start();
</span><span class="lines">@@ -692,22 +818,30 @@
</span><span class="cx"> /**
</span><span class="cx"> * Add hooks for the customizer preview
</span><span class="cx"> *
</span><del>- * @action customize_preview_init
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
</ins><span class="cx"> */
</span><span class="cx"> static function customize_preview_init() {
</span><del>- add_filter( 'sidebars_widgets', array( __CLASS__, 'preview_sidebars_widgets' ), 1 );
</del><ins>+ add_filter( 'sidebars_widgets', array( __CLASS__, 'preview_sidebars_widgets' ), 1 );
</ins><span class="cx"> add_action( 'wp_enqueue_scripts', array( __CLASS__, 'customize_preview_enqueue' ) );
</span><del>- add_action( 'wp_print_styles', array( __CLASS__, 'inject_preview_css' ), 1 );
- add_action( 'wp_footer', array( __CLASS__, 'export_preview_data' ), 20 );
</del><ins>+ add_action( 'wp_print_styles', array( __CLASS__, 'inject_preview_css' ), 1 );
+ add_action( 'wp_footer', array( __CLASS__, 'export_preview_data' ), 20 );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ *
+ *
</ins><span class="cx"> * When previewing, make sure the proper previewing widgets are used. Because wp_get_sidebars_widgets()
</span><span class="cx"> * gets called early at init (via wp_convert_widget_settings()) and can set global variable
</span><span class="cx"> * $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' ) before the customizer
</span><span class="cx"> * preview filter is added, we have to reset it after the filter has been added.
</span><span class="cx"> *
</span><del>- * @filter sidebars_widgets
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param array $sidebars_widgets List of widgets for the current sidebar.
</ins><span class="cx"> */
</span><span class="cx"> static function preview_sidebars_widgets( $sidebars_widgets ) {
</span><span class="cx"> $sidebars_widgets = get_option( 'sidebars_widgets' );
</span><span class="lines">@@ -718,7 +852,9 @@
</span><span class="cx"> /**
</span><span class="cx"> * Enqueue scripts for the customizer preview
</span><span class="cx"> *
</span><del>- * @action wp_enqueue_scripts
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
</ins><span class="cx"> */
</span><span class="cx"> static function customize_preview_enqueue() {
</span><span class="cx"> wp_enqueue_script( 'customize-preview-widgets' );
</span><span class="lines">@@ -728,6 +864,10 @@
</span><span class="cx"> * Insert default style for highlighted widget at early point so theme
</span><span class="cx"> * stylesheet can override.
</span><span class="cx"> *
</span><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
</ins><span class="cx"> * @action wp_print_styles
</span><span class="cx"> */
</span><span class="cx"> static function inject_preview_css() {
</span><span class="lines">@@ -745,9 +885,11 @@
</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><del>- * @action wp_footer
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
</ins><span class="cx"> */
</span><span class="cx"> static function export_preview_data() {
</span><span class="cx"> // Prepare customizer settings to pass to Javascript.
</span><span class="lines">@@ -771,13 +913,14 @@
</span><span class="cx"> <?php
</span><span class="cx"> }
</span><span class="cx">
</span><del>- static protected $rendered_sidebars = array();
- static protected $rendered_widgets = array();
-
</del><span class="cx"> /**
</span><span class="cx"> * Keep track of the widgets that were rendered
</span><span class="cx"> *
</span><del>- * @action dynamic_sidebar
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param array $widget Rendered widget to tally.
</ins><span class="cx"> */
</span><span class="cx"> static function tally_rendered_widgets( $widget ) {
</span><span class="cx"> self::$rendered_widgets[$widget['id']] = true;
</span><span class="lines">@@ -787,7 +930,12 @@
</span><span class="cx"> * Keep track of the times that is_active_sidebar() is called in the template, and assume that this
</span><span class="cx"> * means that the sidebar would be rendered on the template if there were widgets populating it.
</span><span class="cx"> *
</span><del>- * @filter is_active_sidebar
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param bool $is_active Whether the sidebar is active.
+ * @pasram string $sidebar_id Sidebar ID.
</ins><span class="cx"> */
</span><span class="cx"> static function tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id ) {
</span><span class="cx"> if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
</span><span class="lines">@@ -802,25 +950,38 @@
</span><span class="cx"> * Keep track of the times that dynamic_sidebar() is called in the template, and assume that this
</span><span class="cx"> * means that the sidebar would be rendered on the template if there were widgets populating it.
</span><span class="cx"> *
</span><del>- * @filter dynamic_sidebar_has_widgets
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param bool $has_widgets Whether the current sidebar has widgets.
+ * @param string $sidebar_id Sidebar ID.
</ins><span class="cx"> */
</span><span class="cx"> static function tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id ) {
</span><span class="cx"> if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
</span><span class="cx"> self::$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 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 that there is an area to drop widgets into, if the sidebar is empty.
+ */
</ins><span class="cx"> return $has_widgets;
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ * Get a widget instance's hash key.
+ *
</ins><span class="cx"> * Serialize an instance and hash it with the AUTH_KEY; when a JS value is
</span><span class="cx"> * posted back to save, this instance hash key is used to ensure that the
</span><span class="cx"> * serialized_instance was not tampered with, but that it had originated
</span><span class="cx"> * from WordPress and so is sanitized.
</span><span class="cx"> *
</span><del>- * @param array $instance
- * @return string
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access protected
+ *
+ * @param array $instance Widget instance.
+ * @return string Widget instance's hash key.
</ins><span class="cx"> */
</span><span class="cx"> protected static function get_instance_hash_key( $instance ) {
</span><span class="cx"> $hash = md5( AUTH_KEY . serialize( $instance ) );
</span><span class="lines">@@ -828,13 +989,19 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><ins>+ * Sanitize a widget instance.
+ *
</ins><span class="cx"> * Unserialize the JS-instance for storing in the options. It's important
</span><span class="cx"> * that this filter only get applied to an instance once.
</span><span class="cx"> *
</span><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
</ins><span class="cx"> * @see Widget_Customizer::sanitize_widget_js_instance()
</span><span class="cx"> *
</span><del>- * @param array $value
- * @return array
</del><ins>+ * @param array $value Widget instance to sanitize.
+ * @return array Sanitized widget instance.
</ins><span class="cx"> */
</span><span class="cx"> static function sanitize_widget_instance( $value ) {
</span><span class="cx"> if ( $value === array() ) {
</span><span class="lines">@@ -865,12 +1032,16 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Convert widget instance into JSON-representable format
</del><ins>+ * Convert widget instance into JSON-representable format.
</ins><span class="cx"> *
</span><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
</ins><span class="cx"> * @see Widget_Customizer::sanitize_widget_instance()
</span><span class="cx"> *
</span><del>- * @param array $value
- * @return array
</del><ins>+ * @param array $value Widget instance to convert to JSON.
+ * @return array JSON-converted widget instance.
</ins><span class="cx"> */
</span><span class="cx"> static function sanitize_widget_js_instance( $value ) {
</span><span class="cx"> if ( empty( $value['is_widget_customizer_js_value'] ) ) {
</span><span class="lines">@@ -889,8 +1060,12 @@
</span><span class="cx"> * Strip out widget IDs for widgets which are no longer registered, such
</span><span class="cx"> * as the case when a plugin orphans a widget in a sidebar when it is deactivated.
</span><span class="cx"> *
</span><del>- * @param array $widget_ids
- * @return array
</del><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param array $widget_ids List of widget IDs.
+ * @return array Parsed list of widget IDs.
</ins><span class="cx"> */
</span><span class="cx"> static function sanitize_sidebar_widgets_js_instance( $widget_ids ) {
</span><span class="cx"> global $wp_registered_widgets;
</span><span class="lines">@@ -899,11 +1074,16 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Find and invoke the widget update and control callbacks. Requires that
- * $_POST be populated with the instance data.
</del><ins>+ * Find and invoke the widget update and control callbacks.
</ins><span class="cx"> *
</span><del>- * @param string $widget_id
- * @return WP_Error|array
</del><ins>+ * Requires that $_POST be populated with the instance data.
+ *
+ * @since 3.9.0
+ * @static
+ * @access public
+ *
+ * @param string $widget_id Widget ID.
+ * @return WP_Error|array Array containing the updated widget information. WP_Error, otherwise.
</ins><span class="cx"> */
</span><span class="cx"> static function call_widget_update( $widget_id ) {
</span><span class="cx"> global $wp_registered_widget_updates, $wp_registered_widget_controls;
</span><span class="lines">@@ -914,7 +1094,7 @@
</span><span class="cx"> $parsed_id = self::parse_widget_id( $widget_id );
</span><span class="cx"> $option_name = 'widget_' . $parsed_id['id_base'];
</span><span class="cx">
</span><del>- /**
</del><ins>+ /*
</ins><span class="cx"> * If a previously-sanitized instance is provided, populate the input vars
</span><span class="cx"> * with its values so that the widget update callback will read this instance
</span><span class="cx"> */
</span><span class="lines">@@ -946,9 +1126,7 @@
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="cx">
</span><del>- /**
- * Invoke the widget update callback
- */
</del><ins>+ // Invoke the widget update callback.
</ins><span class="cx"> foreach ( (array) $wp_registered_widget_updates as $name => $control ) {
</span><span class="cx"> if ( $name === $parsed_id['id_base'] && is_callable( $control['callback'] ) ) {
</span><span class="cx"> ob_start();
</span><span class="lines">@@ -964,9 +1142,7 @@
</span><span class="cx"> unset( $_REQUEST[$key] );
</span><span class="cx"> }
</span><span class="cx">
</span><del>- /**
- * Make sure the expected option was updated
- */
</del><ins>+ // Make sure the expected option was updated.
</ins><span class="cx"> if ( 0 !== $options_transaction->count() ) {
</span><span class="cx"> if ( count( $options_transaction->options ) > 1 ) {
</span><span class="cx"> $options_transaction->rollback();
</span><span class="lines">@@ -980,9 +1156,7 @@
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="cx">
</span><del>- /**
- * Obtain the widget control with the updated instance in place
- */
</del><ins>+ // Obtain the widget control with the updated instance in place.
</ins><span class="cx"> ob_start();
</span><span class="cx"> $form = $wp_registered_widget_controls[$widget_id];
</span><span class="cx"> if ( $form ) {
</span><span class="lines">@@ -990,9 +1164,7 @@
</span><span class="cx"> }
</span><span class="cx"> $form = ob_get_clean();
</span><span class="cx">
</span><del>- /**
- * Obtain the widget instance
- */
</del><ins>+ // Obtain the widget instance.
</ins><span class="cx"> $option = get_option( $option_name );
</span><span class="cx"> if ( null !== $parsed_id['number'] ) {
</span><span class="cx"> $instance = $option[$parsed_id['number']];
</span><span class="lines">@@ -1009,6 +1181,10 @@
</span><span class="cx"> * instance info via Ajax instead of saving it to the options table.
</span><span class="cx"> * Most code here copied from wp_ajax_save_widget()
</span><span class="cx"> *
</span><ins>+ * @since 3.9.0
+ * @static
+ * @access public
+ *
</ins><span class="cx"> * @see wp_ajax_save_widget
</span><span class="cx"> * @todo Reuse wp_ajax_save_widget now that we have option transactions?
</span><span class="cx"> * @action wp_ajax_update_widget
</span></span></pre>
</div>
</div>
</body>
</html>