[wp-trac] [WordPress Trac] #27993: Support for contexts in the Customizer

[WordPress Trac]

#27993: Support for contexts in the Customizer
-----------------------------+-----------------------------
 Reporter:  danielbachhuber  |       Owner:
     Type:  enhancement      |      Status:  new
 Priority:  normal           |   Milestone:  4.0
Component:  Customize        |     Version:
 Severity:  normal           |  Resolution:
 Keywords:  has-patch        |     Focuses:  ui, javascript
-----------------------------+-----------------------------
Changes (by westonruter):

 * keywords:  needs-patch => has-patch
 * focuses:   => ui, javascript
 * milestone:  Future Release => 4.0


Comment:

 In [attachment:27993.diff], introduce `WP_Customize_Control::active()` to
 access whether the control is relevant to the current context (i.e. to the
 current URL being previewed). Control can indicate its active state by a
 subclass overriding the `active_callback` method, by supplying a callable
 `active_callback` argument into the control’s constructor, or by filtering
 `customize_control_active`.

 When the preview loads, the active controls are sent along with the
 `ready` state as a `activeControls` argument. Each control has a new
 `active` state which gets toggled based on the corresponding values in
 `activeControls`. By default, when a control's `active` state becomes
 `false`, the control will `slideUp`, and then `slideDown` when it becomes
 `true` again. Controls may override this default `toggle` behavior by
 overwriting this method.

 I've implemented this new `active` capability for Widget Customizer. The
 `toggle` method for the `WidgetControl` has been overridden to toggle the
 `widget-rendered` class name on the control container, which results in
 the partially-faded widget control title for widgets that are not rendered
 in the current preview (e.g. for Jetpack's Widget Visibility). Likewise,
 the `toggle` method for the `SidebarControl` has also been overridden to
 toggle the visibility the containing Customizer section when the control's
 `active` state is changed.

 Ideally when all controls in a given section are not `active`, the section
 would in general also collapse automatically. The same goes for the new
 Customizer panels (#27406). However, there is currently no JS models
 provided for managing the state of the Sections or Panels. I've filed
 #28709 to introduce these models.

 For some examples.

 To add a control which only appears on the front page, presumably because
 only the `front-page.php` template renders the associated setting, you may
 supply `is_front_page` as the `active_callback` argument:

 {{{
 $wp_customize->add_control( 'front_page_greeting', array(
         'label'      => __( 'Greeting' ),
         'section'    => 'title_tagline',
         'active_callback' => 'is_front_page',
 ) );
 }}}

 Alternatively, you may do so via a subclass:

 {{{
 class WP_Greeting_Control extends WP_Customize_Control {
         // ...

         function active_callback() {
                 return is_front_page();
         }
 }
 }}}

 Or you may do so via the `customize_control_active` filter:

 {{{
 add_filter( 'customize_control_active', function ( $active, $control ) {
         if ( 'front_page_greeting' === $control->id ) {
                 $active = is_front_page();
         }
         return $active;
 }, 10, 2 );
 }}}

 In each case, the `active_callback` will get fired when `customize.php`
 initially loads, and then again when the preview loads (and for each page
 load as the user navigates around the site within the preview). Depending
 on of the control is expected to be hidden more than shown, then it may be
 desirable for the callback to return `false` if `is_admin()` so that it
 would be hidden by default, and then only appear when the user visits a
 URL for which the control is contextual.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/27993#comment:9>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform