WordPress.org

Make WordPress Core

Changeset 27543


Ignore:
Timestamp:
03/14/2014 08:30:54 PM (6 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:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/class-wp-customize-widgets.php

    r27541 r27543  
    4040
    4141        add_action( 'dynamic_sidebar', array( __CLASS__, 'tally_rendered_widgets' ) );
    42         add_action( 'dynamic_sidebar', array( __CLASS__, 'tally_sidebars_via_dynamic_sidebar_actions' ) );
    43         add_filter( 'temp_is_active_sidebar', array( __CLASS__, 'tally_sidebars_via_is_active_sidebar_calls' ), 10, 2 );
    44         add_filter( 'temp_dynamic_sidebar_has_widgets', array( __CLASS__, 'tally_sidebars_via_dynamic_sidebar_calls' ), 10, 2 );
     42        add_filter( 'is_active_sidebar', array( __CLASS__, 'tally_sidebars_via_is_active_sidebar_calls' ), 10, 2 );
     43        add_filter( 'dynamic_sidebar_has_widgets', array( __CLASS__, 'tally_sidebars_via_dynamic_sidebar_calls' ), 10, 2 );
    4544
    4645        /**
     
    816815
    817816    /**
    818      * This is hacky. It is too bad that dynamic_sidebar is not just called once with the $sidebar_id supplied
    819      * This does not get called for a sidebar which lacks widgets.
    820      * See core patch which addresses the problem.
    821      *
    822      * @link http://core.trac.wordpress.org/ticket/25368
    823      * @action dynamic_sidebar
    824      */
    825     static function tally_sidebars_via_dynamic_sidebar_actions( $widget ) {
    826         global $sidebars_widgets;
    827         foreach ( $sidebars_widgets as $sidebar_id => $widget_ids ) {
    828             if ( in_array( $sidebar_id, self::$rendered_sidebars ) ) {
    829                 continue;
    830             }
    831             if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) && is_array( $widget_ids ) && in_array( $widget['id'], $widget_ids ) ) {
    832                 self::$rendered_sidebars[] = $sidebar_id;
    833             }
    834         }
    835     }
    836 
    837     /**
    838817     * Keep track of the times that is_active_sidebar() is called in the template, and assume that this
    839818     * means that the sidebar would be rendered on the template if there were widgets populating it.
    840819     *
    841      * @see http://core.trac.wordpress.org/ticket/25368
    842      * @filter temp_is_active_sidebar
     820     * @filter is_active_sidebar
    843821     */
    844822    static function tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id ) {
     
    846824            self::$rendered_sidebars[] = $sidebar_id;
    847825        }
    848         // We may need to force this to true, and also force-true the value for temp_dynamic_sidebar_has_widgets
     826        // We may need to force this to true, and also force-true the value for dynamic_sidebar_has_widgets
    849827        // if we want to ensure that there is an area to drop widgets into, if the sidebar is empty.
    850828        return $is_active;
     
    855833     * means that the sidebar would be rendered on the template if there were widgets populating it.
    856834     *
    857      * @see http://core.trac.wordpress.org/ticket/25368
    858      * @filter temp_dynamic_sidebar_has_widgets
     835     * @filter dynamic_sidebar_has_widgets
    859836     */
    860837    static function tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id ) {
     
    862839            self::$rendered_sidebars[] = $sidebar_id;
    863840        }
    864         // We may need to force this to true, and also force-true the value for temp_is_active_sidebar
     841        // We may need to force this to true, and also force-true the value for is_active_sidebar
    865842        // if we want to ensure that there is an area to drop widgets into, if the sidebar is empty.
    866843        return $has_widgets;
  • trunk/src/wp-includes/widgets.php

    r27224 r27543  
    861861    $sidebars_widgets = wp_get_sidebars_widgets();
    862862    if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) {
    863         //temporary_hook #25368
    864         do_action( 'temp_dynamic_sidebar_before', $index, false );
    865         //temporary_hook #25368
    866         do_action( 'temp_dynamic_sidebar_after',  $index, false );
    867         //temporary_hook #25368
    868         return apply_filters( 'temp_dynamic_sidebar_has_widgets', false, $index );
    869     }
    870 
    871     //temporary_hook #25368
    872     do_action( 'temp_dynamic_sidebar_before', $index, true );
     863        /** This action is documented in wp-includes/widgets.php */
     864        do_action( 'dynamic_sidebar_before', $index, false );
     865        /** This action is documented in wp-includes/widgets.php */
     866        do_action( 'dynamic_sidebar_after',  $index, false );
     867        /** This filter is documented in wp-includes/widgets.php */
     868        return apply_filters( 'dynamic_sidebar_has_widgets', false, $index );
     869    }
     870
     871    /**
     872     * Fires before widgets are rendered in a dynamic sidebar.
     873     *
     874     * Note: The action also fires for empty sidebars, and on both the front-end
     875     * and back-end, including the Inactive Widgets sidebar on the Widgets screen.
     876     *
     877     * @since 3.9.0
     878     *
     879     * @param int|string $index       Index, name, or ID of the dynamic sidebar.
     880     * @param bool       $has_widgets Whether the sidebar is populated with widgets.
     881     *                                Default true.
     882     */
     883    do_action( 'dynamic_sidebar_before', $index, true );
    873884    $sidebar = $wp_registered_sidebars[$index];
    874885
     
    894905        $params[0]['before_widget'] = sprintf($params[0]['before_widget'], $id, $classname_);
    895906
     907        /**
     908         * Filter the parameters passed to a widget's display callback.
     909         *
     910         * Note: The filter is evaluated on both the front-end and back-end,
     911         * including for the Inactive Widgets sidebar on the Widgets screen.
     912         *
     913         * @since 2.5.0
     914         *
     915         * @see register_sidebar()
     916         *
     917         * @param array $params {
     918         *     @type array $args  {
     919         *         An array of widget display arguments.
     920         *
     921         *         @type string $name          Name of the sidebar the widget is assigned to.
     922         *         @type string $id            ID of the sidebar the widget is assigned to.
     923         *         @type string $description   The sidebar description.
     924         *         @type string $class         CSS class applied to the sidebar container.
     925         *         @type string $before_widget HTML markup to prepend to each widget in the sidebar.
     926         *         @type string $after_widget  HTML markup to append to each widget in the sidebar.
     927         *         @type string $before_title  HTML markup to prepend to the widget title when displayed.
     928         *         @type string $after_title   HTML markup to append to the widget title when displayed.
     929         *         @type string $widget_id     ID of the widget.
     930         *         @type string $widget_name   Name of the widget.
     931         *     }
     932         *     @type array $widget_args {
     933         *         An array of multi-widget arguments.
     934         *
     935         *         @type int $number Number increment used for multiples of the same widget.
     936         *     }
     937         * }
     938         */
    896939        $params = apply_filters( 'dynamic_sidebar_params', $params );
    897940
    898941        $callback = $wp_registered_widgets[$id]['callback'];
    899942
    900         do_action( 'dynamic_sidebar', $wp_registered_widgets[$id] );
     943        /**
     944         * Fires before a widget's display callback is called.
     945         *
     946         * Note: The action fires on both the front-end and back-end, including
     947         * for widgets in the Inactive Widgets sidebar on the Widgets screen.
     948         *
     949         * The action is not fired for empty sidebars.
     950         *
     951         * @since 3.0.0
     952         *
     953         * @param array $widget_id {
     954         *     An associative array of widget arguments.
     955         *
     956         *     @type string $name                Name of the widget.
     957         *     @type string $id                  Widget ID.
     958         *     @type array|callback $callback    When the hook is fired on the front-end, $callback is an array
     959         *                                       containing the widget object. Fired on the back-end, $callback
     960         *                                       is 'wp_widget_control', see $_callback.
     961         *     @type array          $params      An associative array of multi-widget arguments.
     962         *     @type string         $classname   CSS class applied to the widget container.
     963         *     @type string         $description The widget description.
     964         *     @type array          $_callback   When the hook is fired on the back-end, $_callback is populated
     965         *                                       with an array containing the widget object, see $callback.
     966         * }
     967         */
     968        do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] );
    901969
    902970        if ( is_callable($callback) ) {
     
    906974    }
    907975
    908     //temporary_hook #25368
    909     do_action( 'temp_dynamic_sidebar_after', $index, true );
    910     //temporary_hook #25368
    911     $did_one = apply_filters( 'temp_dynamic_sidebar_has_widgets', $did_one, $index );
     976    /**
     977     * Fires after widgets are rendered in a dynamic sidebar.
     978     *
     979     * Note: The action also fires for empty sidebars, and on both the front-end
     980     * and back-end, including the Inactive Widgets sidebar on the Widgets screen.
     981     *
     982     * @since 3.9.0
     983     *
     984     * @param int|string $index       Index, name, or ID of the dynamic sidebar.
     985     * @param bool       $has_widgets Whether the sidebar is populated with widgets.
     986     *                                Default true.
     987     */
     988    do_action( 'dynamic_sidebar_after', $index, true );
     989
     990    /**
     991     * Filter whether a sidebar has widgets.
     992     *
     993     * Note: The filter is also evaluated for empty sidebars, and on both the front-end
     994     * and back-end, including the Inactive Widgets sidebar on the Widgets screen.
     995     *
     996     * @since 3.9.0
     997     *
     998     * @param bool       $did_one Whether at least one widget was rendered in the sidebar.
     999     *                            Default false.
     1000     * @param int|string $index   Index, name, or ID of the dynamic sidebar.
     1001     */
     1002
     1003    $did_one = apply_filters( 'dynamic_sidebar_has_widgets', $did_one, $index );
     1004
    9121005    return $did_one;
    9131006}
     
    9891082    $sidebars_widgets = wp_get_sidebars_widgets();
    9901083    $is_active_sidebar = ! empty( $sidebars_widgets[$index] );
    991     //temporary_hook #25368
    992     $is_active_sidebar = apply_filters( 'temp_is_active_sidebar', $is_active_sidebar, $index );
    993     return $is_active_sidebar;
     1084
     1085    /**
     1086     * Filter whether a dynamic sidebar is considered "active".
     1087     *
     1088     * @since 3.9.0
     1089     *
     1090     * @param bool       $is_active_sidebar Whether or not the sidebar should be considered "active".
     1091     *                                      In other words, whether the sidebar contains any widgets.
     1092     * @param int|string $index             Index, name, or ID of the dynamic sidebar.
     1093     */
     1094    return apply_filters( 'is_active_sidebar', $is_active_sidebar, $index );
    9941095}
    9951096
Note: See TracChangeset for help on using the changeset viewer.