Changeset 27543

Timestamp:

03/14/2014 08:30:54 PM (11 years ago)

Author:

ocean90

Message:

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.

Location:

trunk/src/wp-includes

Files:

• class-wp-customize-widgets.php (modified) (5 diffs)
• widgets.php (modified) (4 diffs)

trunk/src/wp-includes/class-wp-customize-widgets.php

@@ -40 +40 @@
 
         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 );
 
         /**
@@ -816 +815 @@
 
     /**
-     * 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 ) {
@@ -846 +824 @@
             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;
@@ -855 +833 @@
      * 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 ) {
@@ -862 +839 @@
             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;

trunk/src/wp-includes/widgets.php

@@ -861 +861 @@
     $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 );
-    }
-
-    //temporary_hook #25368
-    do_action( 'temp_dynamic_sidebar_before', $index, true );
+        /** 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 );
+    }
+
+    /**
+     * 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];
 
@@ -894 +905 @@
         $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) ) {
@@ -906 +974 @@
     }
 
-    //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;
 }
@@ -989 +1082 @@
     $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 );
 }