WordPress.org

Make WordPress Core

Ticket #25368: 25368.patch

File 25368.patch, 7.0 KB (added by DrewAPicture, 6 years ago)

Second pass of the hook docs

  • src/wp-includes/widgets.php

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