[wp-trac] [WordPress Trac] #38797: api.previewer.refresh() could return a deferred.promise() with custom server data

[WordPress Trac]

#38797: api.previewer.refresh() could return a deferred.promise() with custom
server data
-------------------------+-----------------------------
 Reporter:  nikeo        |      Owner:
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  Customize    |    Version:
 Severity:  normal       |   Keywords:
  Focuses:  javascript   |
-------------------------+-----------------------------
 Following a discussion
 (https://core.trac.wordpress.org/ticket/38728#comment:8) with
 @westonruter, I'd like to propose an enhancement for the
 `api.previewer.refresh(`) method.

 There might be cases when a developer needs to fire a previewer refresh
 after a specific customizer change, and execute other actions when this
 refresh has been done.

 From a general standpoint, I think that the asynchronous nature of the
 refresh makes it a good candidate for returning a deferred promise.

 An example of use case could be that a developer has several predefined
 settings configuration available for a given theme. Each time a
 configuration is switched to, the settings have to be changed to a set of
 predefined values set in the api. Those predefined values are stored
 server side in say a custom post type ( like the changeset for ex. ).
 A way to do that would be to fire an `api.previewer.refresh()` when
 switching to a given predefined configuration, that would be followed on
 `api.previewer.refresh().done( ... )` by an update of the api values, if
 some conditions are met.

 With the current api, we can add callbacks to the `'synced'` previewer
 event, but it will be fired on all `api.previewer.refresh()` calls, with
 no possibility to target a specific refresh situation that should be
 followed by a custom action.

 This problem could be solved by making the refresh return a deferred
 promise. This $.Deferred() would be resolve() in the `onceSynced()`
 callback function (of the current refreh method), taking a
 `sent_preview_data` object as param.

 While this deferred would be implemented in the `api.previewer.refresh(`)
 method of customize-control.js, another minor addition in customize-
 preview.js could allow developers to easily pass custom server data on
 refresh to the panel this way, and then use those data once the refresh is
 done.

 This way, it would be possible to use the following kind of syntax to fire
 an action on demand after a specific refresh().


 {{{
 api.previewer.refresh().done( function( sent_preview_data ) {
  // fire actions after a specific refresh, when the preview is ready and
 synced
  // the sent_preview_data, could be an object sent when the
 api.preview.send( 'synced', preview_data() ),
  // providing customizable server informations that we may need after a
 refresh.
 } );
 }}}



 On the preview side, in order to pass a server data object to the resolve
 refresh, the idea would be to introduce a `new api.Value()` that could be
 populated before the synced event occurence.

 The current code in [customize-
 preview.js]https://core.trac.wordpress.org/browser/trunk/src/wp-
 includes/js/customize-preview.js#L679 :


 {{{
 api.preview.send( 'synced');
 }}}


 could be replaced by :


 {{{
 api.server_data = api.server_data || new api.Value( {} );
 api.trigger('before_synced', api.server_data() );//<= developers can alter
 the api.server_data() here, before it gets sent
 api.preview.send( 'synced', api.server_data() );
 }}}


 This way, a developer could pass custom data to the panel when
 `api.previewer.refresh().done()`, using the `synced` event, with this type
 of code :


 {{{
 <?php
 add_action('wp_footer', function() {
   if ( ! is_customize_preview() )
     return;
   ?>
   <script type="text/javascript">
     jQuery( function( $ ) {
         wp.customize.bind( 'before_synced', function( value ) {
             //the developer sets the server_data here, before it is sent
 to the preview
             wp.customize.server_data( { custom_data : <?php echo
 get_custom_data(); ?> } );
         } );
     } );
   </script>
   <?php
 });
 }}}

--
Ticket URL: <https://core.trac.wordpress.org/ticket/38797>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform