[wp-trac] [WordPress Trac] #31320: Make customizer JavaScript API available during the live preview

[WordPress Trac]

#31320: Make customizer JavaScript API available during the live preview
-------------------------+------------------------------
 Reporter:  Fab1en       |       Owner:
     Type:  enhancement  |      Status:  reopened
 Priority:  normal       |   Milestone:  Awaiting Review
Component:  Customize    |     Version:  4.1
 Severity:  normal       |  Resolution:
 Keywords:  needs-patch  |     Focuses:  javascript
-------------------------+------------------------------

Comment (by westonruter):

 Replying to [comment:2 Fab1en]:
 > Yes, `wp` object is here, `wp.customize` is defined but
 `wp.customize.control` is not, whereas `frame.top.wp.customize.control`
 is.
 > So simply copying the whole customizer API to the passed wp.customize
 object would be fine.

 There are a lot of objects that get created in the Customizer pane:
 objects for settings, controls, sections, and panels. It would be a waste
 to have these duplicated in two separate window objects. I think we would
 be good to eliminate the copies of the values in the preview as well. So
 this is absolutely related to #29288. Transactions wouldn't change
 anything here.

 For the example provided of focusing on a control, there was a specific
 implementation of this done for widgets in the Customizer: you can
 shift+click on a widget in the preview and it will focus on the widget
 control in the pane. When clicking in the preview, it
 [https://github.com/xwp/wordpress-
 develop/blob/bde2a220d9a3e45e67c47d2dcd6580a05cd6914d/src/wp-includes/js
 /customize-preview-widgets.js#L102 does this]:

 {{{#!js
 wp.customize.preview.send( 'focus-widget-control', widgetId );
 }}}

 And then in the Customizer pane it [https://github.com/xwp/wordpress-
 develop/blob/bde2a220d9a3e45e67c47d2dcd6580a05cd6914d/src/wp-admin/js
 /customize-widgets.js#L1886-L1887 does]:

 {{{#!js
 wp.customize.previewer.bind( 'focus-widget-control',
 wp.customize.Widgets.focusWidgetFormControl );
 }}}

 So this is an ad hoc way of accessing methods on the objects in the
 parent. It's easy to implement.

 If we wanted a generalized framework for accessing parent methods we could
 do something like the following in the Customize preview:

 {{{#!js
 var commandCallbacks = {}, commandId = 0;
 wp.customize.parentProxyCommand = function ( objectType, objectId, method,
 args, callback ) {
         commandId += 1;
         commandCallbacks[ commandId ] = callback;
         wp.customize.preview.send( 'customize-parent-proxy-command',
 objectType, objectId, args, commandId );
 };
 wp.customize.preview.bind( 'customize-parent-proxy-command', function (
 commandId, retval ) {
         var callback = commandCallbacks[ commandId ];
         if ( callback ) {
                 callback( retval );
                 delete commandCallbacks[ commandId ];
         }
 } );
 }}}

 And then in the Customize pane:

 {{{#!js
 wp.customize.previewer.bind( 'customize-parent-proxy-command', function (
 commandId, objectType, objectId, method, args ) {
         wp.customize[ objectType ]( id, function ( object ) {
                 var retval = object[ method ].apply( object, args );
                 wp.customize.previewer.send( 'customize-parent-proxy-
 response', commandId, retval );
         } );
 } );
 }}}

 Then to call the `focus` method on the pane's `blogname` control from
 within the preview, you could do:

 {{{#!js
 wp.customize.parentProxyCommand( 'control', 'blogname', 'focus' );
 }}}

 You could also get the return value and pass arguments to whatever method
 you call as well. Obviously the JS API could be nicer here :-) Too many
 positional parameters. We could even implement the same
 `wp.customize.control( 'blogname' ).focus()` interface in the preview, but
 it would not refer to any `blogname` located within the preview, but would
 instead call the above asynchronous postMessage logic.

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