Index: src/wp-includes/class-wp-customize-widgets.php =================================================================== --- src/wp-includes/class-wp-customize-widgets.php (revision 27747) +++ src/wp-includes/class-wp-customize-widgets.php (working copy) @@ -1,6 +1,12 @@ is_preview() is true here? @@ -242,7 +317,11 @@ /** * Register customizer settings and controls for all sidebars and widgets * - * @action customize_register + * @since 3.9.0 + * @static + * @access public + * + * @param WP_Customize_Manager $wp_customize Customizer instance. */ static function customize_register( $wp_customize = null ) { global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_sidebars; @@ -258,7 +337,7 @@ $new_setting_ids = array(); - /** + /* * 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). */ @@ -318,11 +397,10 @@ } } - /** - * Add a control for each active widget (located in a sidebar) - */ + // Add a control for each active widget (located in a sidebar). foreach ( $sidebar_widget_ids as $i => $widget_id ) { - // Skip widgets that may have gone away due to a plugin being deactivated + + // Skip widgets that may have gone away due to a plugin being deactivated. if ( ! $is_active_sidebar || ! isset( $GLOBALS['wp_registered_widgets'][$widget_id] ) ) { continue; } @@ -349,10 +427,9 @@ } } - /** - * 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() + /* + * We have to register these settings later than customize_preview_init + * so that other filters have had a chance to run. */ if ( did_action( 'customize_preview_init' ) ) { foreach ( $new_setting_ids as $new_setting_id ) { @@ -366,9 +443,12 @@ /** * Covert a widget_id into its corresponding customizer setting id (option name) * - * @param string $widget_id - * @see _get_widget_id_base() - * @return string + * @since 3.9.0 + * @static + * @access public + * + * @param string $widget_id Widget ID. + * @return string Maybe-parsed widget ID. */ static function get_setting_id( $widget_id ) { $parsed_widget_id = self::parse_widget_id( $widget_id ); @@ -387,8 +467,12 @@ * not wide, but this can be overridden with the is_wide_widget_in_customizer * filter. * - * @param string $widget_id - * @return bool + * @since 3.9.0 + * @static + * @access public + * + * @param string $widget_id Widget ID. + * @return bool Whether or not the widget is a "wide" widget. */ static function is_wide_widget( $widget_id ) { global $wp_registered_widget_controls; @@ -396,15 +480,28 @@ $width = $wp_registered_widget_controls[$widget_id]['width']; $is_core = in_array( $parsed_widget_id['id_base'], self::$core_widget_id_bases ); $is_wide = ( $width > 250 && ! $is_core ); + + /** + * 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. + */ $is_wide = apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id ); return $is_wide; } /** - * Covert a widget ID into its id_base and number components + * Covert a widget ID into its id_base and number components. * - * @param string $widget_id - * @return array + * @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. */ static function parse_widget_id( $widget_id ) { $parsed = array( @@ -422,10 +519,15 @@ } /** - * Convert a widget setting ID (option path) to its id_base and number components + * Convert a widget setting ID (option path) to its id_base and number components. * - * @param string $setting_id - * @return WP_Error|array + * @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. */ static function parse_widget_setting_id( $setting_id ) { if ( ! preg_match( '/^(widget_(.+?))(?:\[(\d+)\])?$/', $setting_id, $matches ) ) { @@ -438,9 +540,11 @@ } /** - * Enqueue scripts and styles for customizer panel and export data to JS + * Enqueue scripts and styles for customizer panel and export data to JS. * - * @action customize_controls_enqueue_scripts + * @since 3.9.0 + * @static + * @access public */ static function customize_controls_enqueue_deps() { wp_enqueue_style( 'customize-widgets' ); @@ -482,7 +586,7 @@ ' ); - // 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; $exports = array( 'update_widget_ajax_action' => self::UPDATE_WIDGET_AJAX_ACTION, @@ -518,7 +622,9 @@ /** * Render the widget form control templates into the DOM so that plugin scripts can manipulate them * - * @action customize_controls_print_footer_scripts + * @since 3.9.0 + * @static + * @access public */ static function output_widget_control_templates() { ?> @@ -540,9 +646,13 @@ /** * Get common arguments to supply when constructing a customizer setting * - * @param string $id - * @param array [$overrides] - * @return array + * @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. */ static function get_setting_args( $id, $overrides = array() ) { $args = array( @@ -560,8 +670,12 @@ * Make sure that a sidebars_widgets[x] only ever consists of actual widget IDs. * Used as sanitize_callback for each sidebars_widgets setting. * - * @param array $widget_ids - * @return array + * @since 3.9.0 + * @static + * @access public + * + * @param array $widget_ids Array of widget IDs. + * @return array Array of sanitized widget IDs. */ static function sanitize_sidebar_widgets( $widget_ids ) { global $wp_registered_widgets; @@ -576,8 +690,12 @@ } /** - * Build up an index of all available widgets for use in Backbone models + * Build up an index of all available widgets for use in Backbone models. * + * @since 3.9.0 + * @static + * @access public + * * @see wp_list_widgets() * @return array */ @@ -660,22 +778,30 @@ } /** - * Replace with inline closure once on PHP 5.3: - * sort( $array, function ( $a, $b ) { return strnatcasecmp( $a['name'], $b['name'] ); } ); + * Naturally order available widgets by name. * - * @access private + * @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. */ - static function _sort_name_callback( $a, $b ) { - return strnatcasecmp( $a['name'], $b['name'] ); + static function _sort_name_callback( $widget_a, $widget_b ) { + return strnatcasecmp( $widget_a['name'], $widget_b['name'] ); } /** * Invoke wp_widget_control() but capture the output buffer and transform the markup * so that it can be used in the customizer. * - * @see wp_widget_control() - * @param array $args - * @return string + * @since 3.9.0 + * @static + * @access public + * + * @param array $args Widget control arguments. + * @return string Widget control form HTML markup. */ static function get_widget_control( $args ) { ob_start(); @@ -692,22 +818,30 @@ /** * Add hooks for the customizer preview * - * @action customize_preview_init + * @since 3.9.0 + * @static + * @access public */ static function customize_preview_init() { - add_filter( 'sidebars_widgets', array( __CLASS__, 'preview_sidebars_widgets' ), 1 ); + add_filter( 'sidebars_widgets', array( __CLASS__, 'preview_sidebars_widgets' ), 1 ); add_action( 'wp_enqueue_scripts', array( __CLASS__, 'customize_preview_enqueue' ) ); - add_action( 'wp_print_styles', array( __CLASS__, 'inject_preview_css' ), 1 ); - add_action( 'wp_footer', array( __CLASS__, 'export_preview_data' ), 20 ); + add_action( 'wp_print_styles', array( __CLASS__, 'inject_preview_css' ), 1 ); + add_action( 'wp_footer', array( __CLASS__, 'export_preview_data' ), 20 ); } /** + * + * * 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. * - * @filter sidebars_widgets + * @since 3.9.0 + * @static + * @access public + * + * @param array $sidebars_widgets List of widgets for the current sidebar. */ static function preview_sidebars_widgets( $sidebars_widgets ) { $sidebars_widgets = get_option( 'sidebars_widgets' ); @@ -718,7 +852,9 @@ /** * Enqueue scripts for the customizer preview * - * @action wp_enqueue_scripts + * @since 3.9.0 + * @static + * @access public */ static function customize_preview_enqueue() { wp_enqueue_script( 'customize-preview-widgets' ); @@ -728,6 +864,10 @@ * Insert default style for highlighted widget at early point so theme * stylesheet can override. * + * @since 3.9.0 + * @static + * @access public + * * @action wp_print_styles */ static function inject_preview_css() { @@ -745,9 +885,11 @@ } /** - * 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. * - * @action wp_footer + * @since 3.9.0 + * @static + * @access public */ static function export_preview_data() { // Prepare customizer settings to pass to Javascript. @@ -771,13 +913,14 @@ $control ) { if ( $name === $parsed_id['id_base'] && is_callable( $control['callback'] ) ) { ob_start(); @@ -964,9 +1142,7 @@ unset( $_REQUEST[$key] ); } - /** - * Make sure the expected option was updated - */ + // Make sure the expected option was updated. if ( 0 !== $options_transaction->count() ) { if ( count( $options_transaction->options ) > 1 ) { $options_transaction->rollback(); @@ -980,9 +1156,7 @@ } } - /** - * Obtain the widget control with the updated instance in place - */ + // Obtain the widget control with the updated instance in place. ob_start(); $form = $wp_registered_widget_controls[$widget_id]; if ( $form ) { @@ -990,9 +1164,7 @@ } $form = ob_get_clean(); - /** - * Obtain the widget instance - */ + // Obtain the widget instance. $option = get_option( $option_name ); if ( null !== $parsed_id['number'] ) { $instance = $option[$parsed_id['number']]; @@ -1009,6 +1181,10 @@ * instance info via Ajax instead of saving it to the options table. * Most code here copied from wp_ajax_save_widget() * + * @since 3.9.0 + * @static + * @access public + * * @see wp_ajax_save_widget * @todo Reuse wp_ajax_save_widget now that we have option transactions? * @action wp_ajax_update_widget