[wp-trac] [WordPress Trac] #38799: Normalize the registration of settings and control dependencies in the customize api

[WordPress Trac]

#38799: Normalize the registration of settings and control dependencies in the
customize api
-------------------------+------------------------------
 Reporter:  nikeo        |       Owner:
     Type:  enhancement  |      Status:  new
 Priority:  low          |   Milestone:  Awaiting Review
Component:  Customize    |     Version:
 Severity:  normal       |  Resolution:
 Keywords:               |     Focuses:  javascript
-------------------------+------------------------------

Comment (by nikeo):

 @westonruter @celloexpressions
 I have posted
 [https://gist.github.com/Nikeo/797064befffd3f42beb9b252e83e6ce2 a gist]
 that you can use as a plugin for TwentySeventeen in functions.php.

 The goal is to illustrate a way to simplify some possible patterns that
 are needed when developping a theme or plugin.

 The dependencies are described by a `dependencyMap` collection, and are
 fired on section expansion.

 You can test this code by playing with the settings, and by navigating in
 the preview to trigger server active_callback refreshs.

 == Questions / patterns adressed ==
 Going more into details, the gist tries to address the following
 problems/questions that I have faced when developing themes :
 **active_callback**
 How to make sure that the server active_callback and the js visibility
 play nice together ? The usual problem I have is a control getting a wrong
 visibility state when the `api.previewer.refresh()` is completed, and the
 `control.active()` state has changed in the api, according to what has
 been sent by the server.

 In the example, "dependant one" and "dependant one option" are defined
 server side to be only be display on home page. Those controls should then
 be collapsed when navigating out of home in the preview, and expanded
 again when back home.

 **consistent toggle effect**
 The goal is to have the same expand/collapse effect accross the api for
 both active callbacks and user visibility callbacks.The example uses the
 same reveal method for both : `api.Control.onChangeActive()`

 **multiple visibility dependencies**
 How to handle the case when a control visibility depends on several
 setting values ?
 In the example, dependant three is only displayed when master two and
 three are checked. To solve this problem, I use a collection a visibility
 boolean populated from multiple sources : control active() states and
 master(s) visiblity callbacks. The final control visibility boolean is the
 flat result of this collection => true only if all are true.

 **nested visibilities**
 There are cases when a control is dependant of setting which is dependant
 of another setting. This can typically occurs when we need to define a
 group of customizer setting, working together like a module.
 In the example, "dependant_option_one" depends on "dependant_one" which
 depends on "master_one". You can test it by playing with the two masters,
 and by navigating in the preview to trigger server active_callbacks
 refreshs.

 **individual dependency visibility callbacks**
 It can be tricky to define a visibility rules that says : if setting A is
 set to this value, display control B and hide control C.
 In the example, the visibility callback is called with the dependant
 control `this`. It makes it easy to apply specific visibility condition
 for each dependant controls.

 **defining several sets of dependency settings for the same master**
 Describing the dependency as a collection of normalized objects having all
 the same properties (master, dependants, ... ) makes it easier to define
 several set of dependencies for the same master.


 **dependencies can also be actions**
 While this code is mostly designed to handle the visibility dependencies,
 I think that it might be interesting to also allow actions callback.
 A visibility callback should typically returns a boolean. An action
 callback returns nothing but can execute contextual actions like setting a
 value or changing the style of control, or even display some additional
 description.
 In the example, the `this` of action callbacks is assigned with the
 dependant control, and the master setting id is used as parameter to the
 callback, just like for visibilities. This makes it easier to setup
 individual actions by controls.

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