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
This commit is contained in:
Dominik Schilling 2014-03-14 20:31:14 +00:00
parent 12034fcc59
commit 6b27155163
2 changed files with 123 additions and 45 deletions

View File

@ -39,9 +39,8 @@ class WP_Customize_Widgets {
add_action( 'customize_preview_init', array( __CLASS__, 'customize_preview_init' ) ); 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_rendered_widgets' ) );
add_action( 'dynamic_sidebar', array( __CLASS__, 'tally_sidebars_via_dynamic_sidebar_actions' ) ); add_filter( 'is_active_sidebar', array( __CLASS__, 'tally_sidebars_via_is_active_sidebar_calls' ), 10, 2 );
add_filter( 'temp_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 );
add_filter( 'temp_dynamic_sidebar_has_widgets', array( __CLASS__, 'tally_sidebars_via_dynamic_sidebar_calls' ), 10, 2 );
/** /**
* Special filter for Settings Revisions plugin until it can handle * Special filter for Settings Revisions plugin until it can handle
@ -814,38 +813,17 @@ class WP_Customize_Widgets {
self::$rendered_widgets[$widget['id']] = true; 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 * 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. * 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 is_active_sidebar
* @filter temp_is_active_sidebar
*/ */
static function tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id ) { static function tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id ) {
if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) { if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
self::$rendered_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. // if we want to ensure that there is an area to drop widgets into, if the sidebar is empty.
return $is_active; 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 * 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. * 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 dynamic_sidebar_has_widgets
* @filter temp_dynamic_sidebar_has_widgets
*/ */
static function tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id ) { static function tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id ) {
if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) { if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
self::$rendered_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. // if we want to ensure that there is an area to drop widgets into, if the sidebar is empty.
return $has_widgets; return $has_widgets;
} }

View File

@ -860,16 +860,27 @@ function dynamic_sidebar($index = 1) {
$sidebars_widgets = wp_get_sidebars_widgets(); $sidebars_widgets = wp_get_sidebars_widgets();
if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) { if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) {
//temporary_hook #25368 /** This action is documented in wp-includes/widgets.php */
do_action( 'temp_dynamic_sidebar_before', $index, false ); do_action( 'dynamic_sidebar_before', $index, false );
//temporary_hook #25368 /** This action is documented in wp-includes/widgets.php */
do_action( 'temp_dynamic_sidebar_after', $index, false ); do_action( 'dynamic_sidebar_after', $index, false );
//temporary_hook #25368 /** This filter is documented in wp-includes/widgets.php */
return apply_filters( 'temp_dynamic_sidebar_has_widgets', false, $index ); 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]; $sidebar = $wp_registered_sidebars[$index];
$did_one = false; $did_one = false;
@ -893,11 +904,68 @@ function dynamic_sidebar($index = 1) {
$classname_ = ltrim($classname_, '_'); $classname_ = ltrim($classname_, '_');
$params[0]['before_widget'] = sprintf($params[0]['before_widget'], $id, $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 ); $params = apply_filters( 'dynamic_sidebar_params', $params );
$callback = $wp_registered_widgets[$id]['callback']; $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) ) { if ( is_callable($callback) ) {
call_user_func_array($callback, $params); 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 ); * Fires after widgets are rendered in a dynamic sidebar.
//temporary_hook #25368 *
$did_one = apply_filters( 'temp_dynamic_sidebar_has_widgets', $did_one, $index ); * 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; return $did_one;
} }
@ -988,9 +1081,17 @@ function is_active_sidebar( $index ) {
$index = ( is_int($index) ) ? "sidebar-$index" : sanitize_title($index); $index = ( is_int($index) ) ? "sidebar-$index" : sanitize_title($index);
$sidebars_widgets = wp_get_sidebars_widgets(); $sidebars_widgets = wp_get_sidebars_widgets();
$is_active_sidebar = ! empty( $sidebars_widgets[$index] ); $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 */ /* Internal Functions */