Add temp hooks for Widgets UI Refresh plugin-as-feature

[westonruter]

In the Widgets UI Refresh feature-as-plugin group, one of the things we've discussed is using the Customizer to manage the widgets: to add them, edit them, re-arrange them, and remove them. In order for a widget to be draggable into the Customizer preview to drop onto a sidebar, there must first be a sidebar container element to serve as the drop zone. Unfortunately, the dynamic_sidebar action only fires if there are widgets populating that sidebar (and in fact, it fires once per widget as they are looped over). If a sidebar is empty you cannot introspect where the sidebar is located in the template. Similarly to dynamic_sidebar is is_active_sidebar, which theme authors may use to wrap an element containing the dynamic_sidebar, but this function has no filter at all.

So we need a total of 4 temp hooks added:

• temp_is_active_sidebar
• temp_dynamic_sidebar_did_one — filter to make sure dynamic_sidebar returns true, as otherwise fallback content may be rendered.
• temp_before_dynamic_sidebar
• temp_after_dynamic_sidebar

With these hooks in place, it is then possible for a plugin to force a sidebar to appear and then to create a widget drop-zone:

add_action( 'customize_preview_init', function () {

	add_filter( 'temp_is_active_sidebar', '__return_true' );
	add_filter( 'temp_dynamic_sidebar_did_one', '__return_true' );

	add_action( 'temp_before_dynamic_sidebar', function ( $index ) {
		printf( '<div class="%s" data-index="%s">', 'widget-drop-zone', esc_attr( $index ) );
	} );

	add_action( 'temp_after_dynamic_sidebar', function ( $index ) {
		printf( '</div><!-- /.widget-drop-zone.%s -->', $index );
	} );

} );

Patch has been attached to this ticket, and commits for this feature have also been pushed to GitHub: ​https://github.com/x-team/WordPress/compare/widgets-ui-refresh-temp-hooks?w=1

/cc @shaunandrews

[westonruter]

The patch is not nearly as large as the diff indicates. See with whitespace differences ignored: ​https://github.com/x-team/WordPress/compare/widgets-ui-refresh-temp-hooks?w=1

[nacin]

In 25580:

Temporary hooks for the widgets feature team in dynamic_sidebar() and is_active_sidebar().

props westonruter.
fixes #25368.

[strangerstudios]

These hooks would be useful outside of the overhaul. Any chance they lose the "temp" prefix in a future version?

[westonruter]

I'd love for them to become permanent. These temp hooks are the only way for code to detect whether or not an emptied sidebar is present on the current template.

[westonruter]

Per discussion in wordpress-ui today: ​https://irclogs.wordpress.org/chanlog.php?channel=wordpress-ui&day=2013-12-16&sort=asc#m144623

I'm re-opening this ticket with the request to strip the temp_ prefixes from these hooks.

[westonruter]

Remove temp_ prefixes for dynamic_sidebar_before, dynamic_sidebar_after, dynamic_sidebar_has_widgets, and is_active_sidebar hooks. Add inline docs for these new hooks and for old dynamic_sidebar action and dynamic_sidebar_params filter.

[DrewAPicture]

Yeah, the hook docs in widgets.php.2.patch​ are going to need some work.

[westonruter]

Replying to DrewAPicture:

Yeah, the hook docs in widgets.php.2.patch​ are going to need some work.

What can we do to improve the hook docs?

[DrewAPicture]

Replying to westonruter:

Replying to DrewAPicture:

Yeah, the hook docs in widgets.php.2.patch​ are going to need some work.

What can we do to improve the hook docs?

I'll work up an improved patch for you this afternoon.

[DrewAPicture]

Second pass of the hook docs

[DrewAPicture]

25368.patch​ is a comprehensive second pass of the hook docs. Things started to get a little murky with the dynamic_sidebar hook so feel free to comment with any changes.

[westonruter]

Replying to DrewAPicture:

25368.patch​ is a comprehensive second pass of the hook docs. Things started to get a little murky with the dynamic_sidebar hook so feel free to comment with any changes.

Regarding @type array|string $callback should the type just be callable? It could be a closure as well.

And then the $params is actually wrapped in another array, so I think the docs should be something like:

@type array   $params { 
        Array of arrays to pass into the widget callback, as the second argument to call_user_func_array

        @type array { 
                An array of multi-widget arguments. 
 
                @type int $number Number increment used for multiples of the same widget. 
        } 
}

Here's a dump of an example registered widget:

Array
(
    [name] => Text
    [id] => text-54
    [callback] => Array
        (
            [0] => WP_Widget_Text Object
                (
                    [id_base] => text
                    [name] => Text
                    [widget_options] => Array
                        (
                            [classname] => widget_text
                            [description] => Arbitrary text or HTML.
                        )

                    [control_options] => Array
                        (
                            [id_base] => text
                            [width] => 400
                            [height] => 350
                        )

                    [number] => 62
                    [id] => text-62
                    [updated] =>
                    [option_name] => widget_text
                )

            [1] => display_callback
        )

    [params] => Array
        (
            [0] => Array
                (
                    [number] => 54
                )

        )

    [classname] => widget_text
    [description] => Arbitrary text or HTML.
)

[helen]

Need to rename these hooks as well as all instances of using them.

[DrewAPicture]

3rd pass

[DrewAPicture]

In 25368.2.patch​, I opted to pass a type of array|callback for the $callback argument, as well as simply define $param as an associative array of multi-widget arguments instead of get into the minutia of the sub-arrays.

The inline docs in this patch look good to go.

[westonruter]

4th pass. Remove temp_ prefix from is_active_sidebar and dynamic_sidebar_has_widgets hooks; eliminate obsolete use of hacky dynamic_sidebar hook. Also on GitHub: ​https://github.com/x-team/wordpress-develop/compare/trac-25368

[ocean90]

In 27543:

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.