From 6b27155163af70fd76ba44fca90cbc3393c4b677 Mon Sep 17 00:00:00 2001 From: Dominik Schilling Date: Fri, 14 Mar 2014 20:31:14 +0000 Subject: [PATCH] Widget Customizer: Make temp hooks final and add inline docs. New hooks are `dynamic_sidebar_before`, `dynamic_sidebar_after`, `dynamic_sidebar_has_widgets ` and `is_active_sidebar`. Remove obsolete use of hacky dynamic_sidebar hook. props westonruter, DrewAPicture. fixes #25368. Built from https://develop.svn.wordpress.org/trunk@27543 git-svn-id: http://core.svn.wordpress.org/trunk@27386 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/class-wp-customize-widgets.php | 35 +----- wp-includes/widgets.php | 133 ++++++++++++++++++--- 2 files changed, 123 insertions(+), 45 deletions(-) diff --git a/wp-includes/class-wp-customize-widgets.php b/wp-includes/class-wp-customize-widgets.php index 249505bdec..94d597452e 100644 --- a/wp-includes/class-wp-customize-widgets.php +++ b/wp-includes/class-wp-customize-widgets.php @@ -39,9 +39,8 @@ class WP_Customize_Widgets { add_action( 'customize_preview_init', array( __CLASS__, 'customize_preview_init' ) ); add_action( 'dynamic_sidebar', array( __CLASS__, 'tally_rendered_widgets' ) ); - add_action( 'dynamic_sidebar', array( __CLASS__, 'tally_sidebars_via_dynamic_sidebar_actions' ) ); - add_filter( 'temp_is_active_sidebar', array( __CLASS__, 'tally_sidebars_via_is_active_sidebar_calls' ), 10, 2 ); - add_filter( 'temp_dynamic_sidebar_has_widgets', array( __CLASS__, 'tally_sidebars_via_dynamic_sidebar_calls' ), 10, 2 ); + 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 ); /** * Special filter for Settings Revisions plugin until it can handle @@ -814,38 +813,17 @@ class WP_Customize_Widgets { self::$rendered_widgets[$widget['id']] = true; } - /** - * This is hacky. It is too bad that dynamic_sidebar is not just called once with the $sidebar_id supplied - * This does not get called for a sidebar which lacks widgets. - * See core patch which addresses the problem. - * - * @link http://core.trac.wordpress.org/ticket/25368 - * @action dynamic_sidebar - */ - static function tally_sidebars_via_dynamic_sidebar_actions( $widget ) { - global $sidebars_widgets; - foreach ( $sidebars_widgets as $sidebar_id => $widget_ids ) { - if ( in_array( $sidebar_id, self::$rendered_sidebars ) ) { - continue; - } - if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) && is_array( $widget_ids ) && in_array( $widget['id'], $widget_ids ) ) { - self::$rendered_sidebars[] = $sidebar_id; - } - } - } - /** * 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. * - * @see http://core.trac.wordpress.org/ticket/25368 - * @filter temp_is_active_sidebar + * @filter is_active_sidebar */ static function tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id ) { if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) { self::$rendered_sidebars[] = $sidebar_id; } - // We may need to force this to true, and also force-true the value for temp_dynamic_sidebar_has_widgets + // 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; } @@ -854,14 +832,13 @@ class WP_Customize_Widgets { * 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. * - * @see http://core.trac.wordpress.org/ticket/25368 - * @filter temp_dynamic_sidebar_has_widgets + * @filter dynamic_sidebar_has_widgets */ static function tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id ) { if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) { self::$rendered_sidebars[] = $sidebar_id; } - // We may need to force this to true, and also force-true the value for temp_is_active_sidebar + // 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. return $has_widgets; } diff --git a/wp-includes/widgets.php b/wp-includes/widgets.php index e27a13de66..c6d0621ca8 100644 --- a/wp-includes/widgets.php +++ b/wp-includes/widgets.php @@ -860,16 +860,27 @@ function dynamic_sidebar($index = 1) { $sidebars_widgets = wp_get_sidebars_widgets(); if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) { - //temporary_hook #25368 - do_action( 'temp_dynamic_sidebar_before', $index, false ); - //temporary_hook #25368 - do_action( 'temp_dynamic_sidebar_after', $index, false ); - //temporary_hook #25368 - return apply_filters( 'temp_dynamic_sidebar_has_widgets', false, $index ); + /** This action is documented in wp-includes/widgets.php */ + do_action( 'dynamic_sidebar_before', $index, false ); + /** This action is documented in wp-includes/widgets.php */ + do_action( 'dynamic_sidebar_after', $index, false ); + /** This filter is documented in wp-includes/widgets.php */ + return apply_filters( 'dynamic_sidebar_has_widgets', false, $index ); } - //temporary_hook #25368 - do_action( 'temp_dynamic_sidebar_before', $index, true ); + /** + * Fires before widgets are rendered in a dynamic sidebar. + * + * Note: The action also fires for empty sidebars, and on both the front-end + * and back-end, including the Inactive Widgets sidebar on the Widgets screen. + * + * @since 3.9.0 + * + * @param int|string $index Index, name, or ID of the dynamic sidebar. + * @param bool $has_widgets Whether the sidebar is populated with widgets. + * Default true. + */ + do_action( 'dynamic_sidebar_before', $index, true ); $sidebar = $wp_registered_sidebars[$index]; $did_one = false; @@ -893,11 +904,68 @@ function dynamic_sidebar($index = 1) { $classname_ = ltrim($classname_, '_'); $params[0]['before_widget'] = sprintf($params[0]['before_widget'], $id, $classname_); + /** + * Filter the parameters passed to a widget's display callback. + * + * Note: The filter is evaluated on both the front-end and back-end, + * including for the Inactive Widgets sidebar on the Widgets screen. + * + * @since 2.5.0 + * + * @see register_sidebar() + * + * @param array $params { + * @type array $args { + * An array of widget display arguments. + * + * @type string $name Name of the sidebar the widget is assigned to. + * @type string $id ID of the sidebar the widget is assigned to. + * @type string $description The sidebar description. + * @type string $class CSS class applied to the sidebar container. + * @type string $before_widget HTML markup to prepend to each widget in the sidebar. + * @type string $after_widget HTML markup to append to each widget in the sidebar. + * @type string $before_title HTML markup to prepend to the widget title when displayed. + * @type string $after_title HTML markup to append to the widget title when displayed. + * @type string $widget_id ID of the widget. + * @type string $widget_name Name of the widget. + * } + * @type array $widget_args { + * An array of multi-widget arguments. + * + * @type int $number Number increment used for multiples of the same widget. + * } + * } + */ $params = apply_filters( 'dynamic_sidebar_params', $params ); $callback = $wp_registered_widgets[$id]['callback']; - do_action( 'dynamic_sidebar', $wp_registered_widgets[$id] ); + /** + * Fires before a widget's display callback is called. + * + * Note: The action fires on both the front-end and back-end, including + * for widgets in the Inactive Widgets sidebar on the Widgets screen. + * + * The action is not fired for empty sidebars. + * + * @since 3.0.0 + * + * @param array $widget_id { + * An associative array of widget arguments. + * + * @type string $name Name of the widget. + * @type string $id Widget ID. + * @type array|callback $callback When the hook is fired on the front-end, $callback is an array + * containing the widget object. Fired on the back-end, $callback + * is 'wp_widget_control', see $_callback. + * @type array $params An associative array of multi-widget arguments. + * @type string $classname CSS class applied to the widget container. + * @type string $description The widget description. + * @type array $_callback When the hook is fired on the back-end, $_callback is populated + * with an array containing the widget object, see $callback. + * } + */ + do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] ); if ( is_callable($callback) ) { call_user_func_array($callback, $params); @@ -905,10 +973,35 @@ function dynamic_sidebar($index = 1) { } } - //temporary_hook #25368 - do_action( 'temp_dynamic_sidebar_after', $index, true ); - //temporary_hook #25368 - $did_one = apply_filters( 'temp_dynamic_sidebar_has_widgets', $did_one, $index ); + /** + * Fires after widgets are rendered in a dynamic sidebar. + * + * Note: The action also fires for empty sidebars, and on both the front-end + * and back-end, including the Inactive Widgets sidebar on the Widgets screen. + * + * @since 3.9.0 + * + * @param int|string $index Index, name, or ID of the dynamic sidebar. + * @param bool $has_widgets Whether the sidebar is populated with widgets. + * Default true. + */ + do_action( 'dynamic_sidebar_after', $index, true ); + + /** + * Filter whether a sidebar has widgets. + * + * Note: The filter is also evaluated for empty sidebars, and on both the front-end + * and back-end, including the Inactive Widgets sidebar on the Widgets screen. + * + * @since 3.9.0 + * + * @param bool $did_one Whether at least one widget was rendered in the sidebar. + * Default false. + * @param int|string $index Index, name, or ID of the dynamic sidebar. + */ + + $did_one = apply_filters( 'dynamic_sidebar_has_widgets', $did_one, $index ); + return $did_one; } @@ -988,9 +1081,17 @@ function is_active_sidebar( $index ) { $index = ( is_int($index) ) ? "sidebar-$index" : sanitize_title($index); $sidebars_widgets = wp_get_sidebars_widgets(); $is_active_sidebar = ! empty( $sidebars_widgets[$index] ); - //temporary_hook #25368 - $is_active_sidebar = apply_filters( 'temp_is_active_sidebar', $is_active_sidebar, $index ); - return $is_active_sidebar; + + /** + * Filter whether a dynamic sidebar is considered "active". + * + * @since 3.9.0 + * + * @param bool $is_active_sidebar Whether or not the sidebar should be considered "active". + * In other words, whether the sidebar contains any widgets. + * @param int|string $index Index, name, or ID of the dynamic sidebar. + */ + return apply_filters( 'is_active_sidebar', $is_active_sidebar, $index ); } /* Internal Functions */