<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[27543] trunk/src/wp-includes: Widget Customizer: Make temp hooks final and add inline docs.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://core.trac.wordpress.org/changeset/27543">27543</a></dd>
<dt>Author</dt> <dd>ocean90</dd>
<dt>Date</dt> <dd>2014-03-14 20:30:54 +0000 (Fri, 14 Mar 2014)</dd>
</dl>
<h3>Log Message</h3>
<pre>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 <a href="http://core.trac.wordpress.org/ticket/25368">#25368</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludesclasswpcustomizewidgetsphp">trunk/src/wp-includes/class-wp-customize-widgets.php</a></li>
<li><a href="#trunksrcwpincludeswidgetsphp">trunk/src/wp-includes/widgets.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludesclasswpcustomizewidgetsphp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/class-wp-customize-widgets.php (27542 => 27543)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/class-wp-customize-widgets.php 2014-03-14 20:25:31 UTC (rev 27542)
+++ trunk/src/wp-includes/class-wp-customize-widgets.php 2014-03-14 20:30:54 UTC (rev 27543)
</span><span class="lines">@@ -39,9 +39,8 @@
</span><span class="cx"> add_action( 'customize_preview_init', array( __CLASS__, 'customize_preview_init' ) );
</span><span class="cx">
</span><span class="cx"> add_action( 'dynamic_sidebar', array( __CLASS__, 'tally_rendered_widgets' ) );
</span><del>- 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 );
</del><ins>+ 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 );
</ins><span class="cx">
</span><span class="cx"> /**
</span><span class="cx"> * Special filter for Settings Revisions plugin until it can handle
</span><span class="lines">@@ -815,37 +814,16 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * 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;
- }
- }
- }
-
- /**
</del><span class="cx"> * Keep track of the times that is_active_sidebar() is called in the template, and assume that this
</span><span class="cx"> * means that the sidebar would be rendered on the template if there were widgets populating it.
</span><span class="cx"> *
</span><del>- * @see http://core.trac.wordpress.org/ticket/25368
- * @filter temp_is_active_sidebar
</del><ins>+ * @filter is_active_sidebar
</ins><span class="cx"> */
</span><span class="cx"> static function tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id ) {
</span><span class="cx"> if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
</span><span class="cx"> self::$rendered_sidebars[] = $sidebar_id;
</span><span class="cx"> }
</span><del>- // We may need to force this to true, and also force-true the value for temp_dynamic_sidebar_has_widgets
</del><ins>+ // We may need to force this to true, and also force-true the value for dynamic_sidebar_has_widgets
</ins><span class="cx"> // if we want to ensure that there is an area to drop widgets into, if the sidebar is empty.
</span><span class="cx"> return $is_active;
</span><span class="cx"> }
</span><span class="lines">@@ -854,14 +832,13 @@
</span><span class="cx"> * Keep track of the times that dynamic_sidebar() is called in the template, and assume that this
</span><span class="cx"> * means that the sidebar would be rendered on the template if there were widgets populating it.
</span><span class="cx"> *
</span><del>- * @see http://core.trac.wordpress.org/ticket/25368
- * @filter temp_dynamic_sidebar_has_widgets
</del><ins>+ * @filter dynamic_sidebar_has_widgets
</ins><span class="cx"> */
</span><span class="cx"> static function tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id ) {
</span><span class="cx"> if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
</span><span class="cx"> self::$rendered_sidebars[] = $sidebar_id;
</span><span class="cx"> }
</span><del>- // We may need to force this to true, and also force-true the value for temp_is_active_sidebar
</del><ins>+ // We may need to force this to true, and also force-true the value for is_active_sidebar
</ins><span class="cx"> // if we want to ensure that there is an area to drop widgets into, if the sidebar is empty.
</span><span class="cx"> return $has_widgets;
</span><span class="cx"> }
</span></span></pre></div>
<a id="trunksrcwpincludeswidgetsphp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/widgets.php (27542 => 27543)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/widgets.php 2014-03-14 20:25:31 UTC (rev 27542)
+++ trunk/src/wp-includes/widgets.php 2014-03-14 20:30:54 UTC (rev 27543)
</span><span class="lines">@@ -860,16 +860,27 @@
</span><span class="cx">
</span><span class="cx"> $sidebars_widgets = wp_get_sidebars_widgets();
</span><span class="cx"> if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) {
</span><del>- //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 );
</del><ins>+ /** 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 );
</ins><span class="cx"> }
</span><span class="cx">
</span><del>- //temporary_hook #25368
- do_action( 'temp_dynamic_sidebar_before', $index, true );
</del><ins>+ /**
+ * 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 );
</ins><span class="cx"> $sidebar = $wp_registered_sidebars[$index];
</span><span class="cx">
</span><span class="cx"> $did_one = false;
</span><span class="lines">@@ -893,11 +904,68 @@
</span><span class="cx"> $classname_ = ltrim($classname_, '_');
</span><span class="cx"> $params[0]['before_widget'] = sprintf($params[0]['before_widget'], $id, $classname_);
</span><span class="cx">
</span><ins>+ /**
+ * 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.
+ * }
+ * }
+ */
</ins><span class="cx"> $params = apply_filters( 'dynamic_sidebar_params', $params );
</span><span class="cx">
</span><span class="cx"> $callback = $wp_registered_widgets[$id]['callback'];
</span><span class="cx">
</span><del>- do_action( 'dynamic_sidebar', $wp_registered_widgets[$id] );
</del><ins>+ /**
+ * 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 ] );
</ins><span class="cx">
</span><span class="cx"> if ( is_callable($callback) ) {
</span><span class="cx"> call_user_func_array($callback, $params);
</span><span class="lines">@@ -905,10 +973,35 @@
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="cx">
</span><del>- //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 );
</del><ins>+ /**
+ * 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 );
+
</ins><span class="cx"> return $did_one;
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -988,9 +1081,17 @@
</span><span class="cx"> $index = ( is_int($index) ) ? "sidebar-$index" : sanitize_title($index);
</span><span class="cx"> $sidebars_widgets = wp_get_sidebars_widgets();
</span><span class="cx"> $is_active_sidebar = ! empty( $sidebars_widgets[$index] );
</span><del>- //temporary_hook #25368
- $is_active_sidebar = apply_filters( 'temp_is_active_sidebar', $is_active_sidebar, $index );
- return $is_active_sidebar;
</del><ins>+
+ /**
+ * 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 );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /* Internal Functions */
</span></span></pre>
</div>
</div>
</body>
</html>