1/**
2 * @output wp-includes/js/customize-preview-widgets.js
3 */
4
5/* global _wpWidgetCustomizerPreviewSettings */
6
7/**
8 * Handles the initialization, refreshing and rendering of widget partials and sidebar widgets.
9 *
10 * @since 4.5.0
11 *
12 * @namespace wp.customize.widgetsPreview
13 *
14 * @param {jQuery} $ The jQuery object.
15 * @param {Object} _ The utilities library.
16 * @param {Object} wp Current WordPress environment instance.
17 * @param {Object} api Information from the API.
18 *
19 * @return {Object} Widget-related variables.
20 */
21wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function( $, _, wp, api ) {
22
23 var self;
24
25 self = {
26 renderedSidebars: {},
27 renderedWidgets: {},
28 registeredSidebars: [],
29 registeredWidgets: {},
30 widgetSelectors: [],
31 preview: null,
32 l10n: {
33 widgetTooltip: ''
34 },
35 selectiveRefreshableWidgets: {}
36 };
37
38 /**
39 * Initializes the widgets preview.
40 *
41 * @since 4.5.0
42 *
43 * @memberOf wp.customize.widgetsPreview
44 *
45 * @return {void}
46 */
47 self.init = function() {
48 var self = this;
49
50 self.preview = api.preview;
51 if ( ! _.isEmpty( self.selectiveRefreshableWidgets ) ) {
52 self.addPartials();
53 }
54
55 self.buildWidgetSelectors();
56 self.highlightControls();
57
58 self.preview.bind( 'highlight-widget', self.highlightWidget );
59
60 api.preview.bind( 'active', function() {
61 self.highlightControls();
62 } );
63
64 /*
65 * Refresh a partial when the controls pane requests it. This is used currently just by the
66 * Gallery widget so that when an attachment's caption is updated in the media modal,
67 * the widget in the preview will then be refreshed to show the change. Normally doing this
68 * would not be necessary because all of the state should be contained inside the changeset,
69 * as everything done in the Customizer should not make a change to the site unless the
70 * changeset itself is published. Attachments are a current exception to this rule.
71 * For a proposal to include attachments in the customized state, see #37887.
72 */
73 api.preview.bind( 'refresh-widget-partial', function( widgetId ) {
74 var partialId = 'widget[' + widgetId + ']';
75 if ( api.selectiveRefresh.partial.has( partialId ) ) {
76 api.selectiveRefresh.partial( partialId ).refresh();
77 } else if ( self.renderedWidgets[ widgetId ] ) {
78 api.preview.send( 'refresh' ); // Fallback in case theme does not support 'customize-selective-refresh-widgets'.
79 }
80 } );
81 };
82
83 self.WidgetPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.WidgetPartial.prototype */{
84
85 /**
86 * Represents a partial widget instance.
87 *
88 * @since 4.5.0
89 *
90 * @constructs
91 * @augments wp.customize.selectiveRefresh.Partial
92 *
93 * @alias wp.customize.widgetsPreview.WidgetPartial
94 * @memberOf wp.customize.widgetsPreview
95 *
96 * @param {string} id The partial's ID.
97 * @param {Object} options Options used to initialize the partial's
98 * instance.
99 * @param {Object} options.params The options parameters.
100 */
101 initialize: function( id, options ) {
102 var partial = this, matches;
103 matches = id.match( /^widget\[(.+)]$/ );
104 if ( ! matches ) {
105 throw new Error( 'Illegal id for widget partial.' );
106 }
107
108 partial.widgetId = matches[1];
109 partial.widgetIdParts = self.parseWidgetId( partial.widgetId );
110 options = options || {};
111 options.params = _.extend(
112 {
113 settings: [ self.getWidgetSettingId( partial.widgetId ) ],
114 containerInclusive: true
115 },
116 options.params || {}
117 );
118
119 api.selectiveRefresh.Partial.prototype.initialize.call( partial, id, options );
120 },
121
122 /**
123 * Refreshes the widget partial.
124 *
125 * @since 4.5.0
126 *
127 * @return {Promise|void} Either a promise postponing the refresh, or void.
128 */
129 refresh: function() {
130 var partial = this, refreshDeferred;
131 if ( ! self.selectiveRefreshableWidgets[ partial.widgetIdParts.idBase ] ) {
132 refreshDeferred = $.Deferred();
133 refreshDeferred.reject();
134 partial.fallback();
135 return refreshDeferred.promise();
136 } else {
137 return api.selectiveRefresh.Partial.prototype.refresh.call( partial );
138 }
139 },
140
141 /**
142 * Sends the widget-updated message to the parent so the spinner will get
143 * removed from the widget control.
144 *
145 * @inheritDoc
146 * @param {wp.customize.selectiveRefresh.Placement} placement The placement
147 * function.
148 *
149 * @return {void}
150 */
151 renderContent: function( placement ) {
152 var partial = this;
153 if ( api.selectiveRefresh.Partial.prototype.renderContent.call( partial, placement ) ) {
154 api.preview.send( 'widget-updated', partial.widgetId );
155 api.selectiveRefresh.trigger( 'widget-updated', partial );
156 }
157 }
158 });
159
160 self.SidebarPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.SidebarPartial.prototype */{
161
162 /**
163 * Represents a partial widget area.
164 *
165 * @since 4.5.0
166 *
167 * @class
168 * @augments wp.customize.selectiveRefresh.Partial
169 *
170 * @memberOf wp.customize.widgetsPreview
171 * @alias wp.customize.widgetsPreview.SidebarPartial
172 *
173 * @param {string} id The partial's ID.
174 * @param {Object} options Options used to initialize the partial's instance.
175 * @param {Object} options.params The options parameters.
176 */
177 initialize: function( id, options ) {
178 var partial = this, matches;
179 matches = id.match( /^sidebar\[(.+)]$/ );
180 if ( ! matches ) {
181 throw new Error( 'Illegal id for sidebar partial.' );
182 }
183 partial.sidebarId = matches[1];
184
185 options = options || {};
186 options.params = _.extend(
187 {
188 settings: [ 'sidebars_widgets[' + partial.sidebarId + ']' ]
189 },
190 options.params || {}
191 );
192
193 api.selectiveRefresh.Partial.prototype.initialize.call( partial, id, options );
194
195 if ( ! partial.params.sidebarArgs ) {
196 throw new Error( 'The sidebarArgs param was not provided.' );
197 }
198 if ( partial.params.settings.length > 1 ) {
199 throw new Error( 'Expected SidebarPartial to only have one associated setting' );
200 }
201 },
202
203 /**
204 * Sets up the partial.
205 *
206 * @since 4.5.0
207 *
208 * @return {void}
209 */
210 ready: function() {
211 var sidebarPartial = this;
212
213 // Watch for changes to the sidebar_widgets setting.
214 _.each( sidebarPartial.settings(), function( settingId ) {
215 api( settingId ).bind( _.bind( sidebarPartial.handleSettingChange, sidebarPartial ) );
216 } );
217
218 // Trigger an event for this sidebar being updated whenever a widget inside is rendered.
219 api.selectiveRefresh.bind( 'partial-content-rendered', function( placement ) {
220 var isAssignedWidgetPartial = (
221 placement.partial.extended( self.WidgetPartial ) &&
222 ( -1 !== _.indexOf( sidebarPartial.getWidgetIds(), placement.partial.widgetId ) )
223 );
224 if ( isAssignedWidgetPartial ) {
225 api.selectiveRefresh.trigger( 'sidebar-updated', sidebarPartial );
226 }
227 } );
228
229 // Make sure that a widget partial has a container in the DOM prior to a refresh.
230 api.bind( 'change', function( widgetSetting ) {
231 var widgetId, parsedId;
232 parsedId = self.parseWidgetSettingId( widgetSetting.id );
233 if ( ! parsedId ) {
234 return;
235 }
236 widgetId = parsedId.idBase;
237 if ( parsedId.number ) {
238 widgetId += '-' + String( parsedId.number );
239 }
240 if ( -1 !== _.indexOf( sidebarPartial.getWidgetIds(), widgetId ) ) {
241 sidebarPartial.ensureWidgetPlacementContainers( widgetId );
242 }
243 } );
244 },
245
246 /**
247 * Gets the before/after boundary nodes for all instances of this sidebar
248 * (usually one).
249 *
250 * Note that TreeWalker is not implemented in IE8.
251 *
252 * @since 4.5.0
253 *
254 * @return {Array.<{before: Comment, after: Comment, instanceNumber: number}>}
255 * An array with an object for each sidebar instance, containing the
256 * node before and after the sidebar instance and its instance number.
257 */
258 findDynamicSidebarBoundaryNodes: function() {
259 var partial = this, regExp, boundaryNodes = {}, recursiveCommentTraversal;
260 regExp = /^(dynamic_sidebar_before|dynamic_sidebar_after):(.+):(\d+)$/;
261 recursiveCommentTraversal = function( childNodes ) {
262 _.each( childNodes, function( node ) {
263 var matches;
264 if ( 8 === node.nodeType ) {
265 matches = node.nodeValue.match( regExp );
266 if ( ! matches || matches[2] !== partial.sidebarId ) {
267 return;
268 }
269 if ( _.isUndefined( boundaryNodes[ matches[3] ] ) ) {
270 boundaryNodes[ matches[3] ] = {
271 before: null,
272 after: null,
273 instanceNumber: parseInt( matches[3], 10 )
274 };
275 }
276 if ( 'dynamic_sidebar_before' === matches[1] ) {
277 boundaryNodes[ matches[3] ].before = node;
278 } else {
279 boundaryNodes[ matches[3] ].after = node;
280 }
281 } else if ( 1 === node.nodeType ) {
282 recursiveCommentTraversal( node.childNodes );
283 }
284 } );
285 };
286
287 recursiveCommentTraversal( document.body.childNodes );
288 return _.values( boundaryNodes );
289 },
290
291 /**
292 * Gets the placements for this partial.
293 *
294 * @since 4.5.0
295 *
296 * @return {Array} An array containing placement objects for each of the
297 * dynamic sidebar boundary nodes.
298 */
299 placements: function() {
300 var partial = this;
301 return _.map( partial.findDynamicSidebarBoundaryNodes(), function( boundaryNodes ) {
302 return new api.selectiveRefresh.Placement( {
303 partial: partial,
304 container: null,
305 startNode: boundaryNodes.before,
306 endNode: boundaryNodes.after,
307 context: {
308 instanceNumber: boundaryNodes.instanceNumber
309 }
310 } );
311 } );
312 },
313
314 /**
315 * Get the list of widget IDs associated with this widget area.
316 *
317 * @since 4.5.0
318 *
319 * @throws {Error} If there's no settingId.
320 * @throws {Error} If the setting doesn't exist in the API.
321 * @throws {Error} If the API doesn't pass an array of widget IDs.
322 *
323 * @return {Array} A shallow copy of the array containing widget IDs.
324 */
325 getWidgetIds: function() {
326 var sidebarPartial = this, settingId, widgetIds;
327 settingId = sidebarPartial.settings()[0];
328 if ( ! settingId ) {
329 throw new Error( 'Missing associated setting.' );
330 }
331 if ( ! api.has( settingId ) ) {
332 throw new Error( 'Setting does not exist.' );
333 }
334 widgetIds = api( settingId ).get();
335 if ( ! _.isArray( widgetIds ) ) {
336 throw new Error( 'Expected setting to be array of widget IDs' );
337 }
338 return widgetIds.slice( 0 );
339 },
340
341 /**
342 * Reflows widgets in the sidebar, ensuring they have the proper position in the
343 * DOM.
344 *
345 * @since 4.5.0
346 *
347 * @return {Array.<wp.customize.selectiveRefresh.Placement>} List of placements
348 * that were reflowed.
349 */
350 reflowWidgets: function() {
351 var sidebarPartial = this, sidebarPlacements, widgetIds, widgetPartials, sortedSidebarContainers = [];
352 widgetIds = sidebarPartial.getWidgetIds();
353 sidebarPlacements = sidebarPartial.placements();
354
355 widgetPartials = {};
356 _.each( widgetIds, function( widgetId ) {
357 var widgetPartial = api.selectiveRefresh.partial( 'widget[' + widgetId + ']' );
358 if ( widgetPartial ) {
359 widgetPartials[ widgetId ] = widgetPartial;
360 }
361 } );
362
363 _.each( sidebarPlacements, function( sidebarPlacement ) {
364 var sidebarWidgets = [], needsSort = false, thisPosition, lastPosition = -1;
365
366 // Gather list of widget partial containers in this sidebar, and determine if a sort is needed.
367 _.each( widgetPartials, function( widgetPartial ) {
368 _.each( widgetPartial.placements(), function( widgetPlacement ) {
369
370 if ( sidebarPlacement.context.instanceNumber === widgetPlacement.context.sidebar_instance_number ) {
371 thisPosition = widgetPlacement.container.index();
372 sidebarWidgets.push( {
373 partial: widgetPartial,
374 placement: widgetPlacement,
375 position: thisPosition
376 } );
377 if ( thisPosition < lastPosition ) {
378 needsSort = true;
379 }
380 lastPosition = thisPosition;
381 }
382 } );
383 } );
384
385 if ( needsSort ) {
386 _.each( sidebarWidgets, function( sidebarWidget ) {
387 sidebarPlacement.endNode.parentNode.insertBefore(
388 sidebarWidget.placement.container[0],
389 sidebarPlacement.endNode
390 );
391
392 // @todo Rename partial-placement-moved?
393 api.selectiveRefresh.trigger( 'partial-content-moved', sidebarWidget.placement );
394 } );
395
396 sortedSidebarContainers.push( sidebarPlacement );
397 }
398 } );
399
400 if ( sortedSidebarContainers.length > 0 ) {
401 api.selectiveRefresh.trigger( 'sidebar-updated', sidebarPartial );
402 }
403
404 return sortedSidebarContainers;
405 },
406
407 /**
408 * Makes sure there is a widget instance container in this sidebar for the given
409 * widget ID.
410 *
411 * @since 4.5.0
412 *
413 * @param {string} widgetId The widget ID.
414 *
415 * @return {wp.customize.selectiveRefresh.Partial} The widget instance partial.
416 */
417 ensureWidgetPlacementContainers: function( widgetId ) {
418 var sidebarPartial = this, widgetPartial, wasInserted = false, partialId = 'widget[' + widgetId + ']';
419 widgetPartial = api.selectiveRefresh.partial( partialId );
420 if ( ! widgetPartial ) {
421 widgetPartial = new self.WidgetPartial( partialId, {
422 params: {}
423 } );
424 }
425
426 // Make sure that there is a container element for the widget in the sidebar, if at least a placeholder.
427 _.each( sidebarPartial.placements(), function( sidebarPlacement ) {
428 var foundWidgetPlacement, widgetContainerElement;
429
430 foundWidgetPlacement = _.find( widgetPartial.placements(), function( widgetPlacement ) {
431 return ( widgetPlacement.context.sidebar_instance_number === sidebarPlacement.context.instanceNumber );
432 } );
433 if ( foundWidgetPlacement ) {
434 return;
435 }
436
437 widgetContainerElement = $(
438 sidebarPartial.params.sidebarArgs.before_widget.replace( /%1\$s/g, widgetId ).replace( /%2\$s/g, 'widget' ) +
439 sidebarPartial.params.sidebarArgs.after_widget
440 );
441
442 // Handle rare case where before_widget and after_widget are empty.
443 if ( ! widgetContainerElement[0] ) {
444 return;
445 }
446
447 widgetContainerElement.attr( 'data-customize-partial-id', widgetPartial.id );
448 widgetContainerElement.attr( 'data-customize-partial-type', 'widget' );
449 widgetContainerElement.attr( 'data-customize-widget-id', widgetId );
450
451 /*
452 * Make sure the widget container element has the customize-container context data.
453 * The sidebar_instance_number is used to disambiguate multiple instances of the
454 * same sidebar are rendered onto the template, and so the same widget is embedded
455 * multiple times.
456 */
457 widgetContainerElement.data( 'customize-partial-placement-context', {
458 'sidebar_id': sidebarPartial.sidebarId,
459 'sidebar_instance_number': sidebarPlacement.context.instanceNumber
460 } );
461
462 sidebarPlacement.endNode.parentNode.insertBefore( widgetContainerElement[0], sidebarPlacement.endNode );
463 wasInserted = true;
464 } );
465
466 api.selectiveRefresh.partial.add( widgetPartial );
467
468 if ( wasInserted ) {
469 sidebarPartial.reflowWidgets();
470 }
471
472 return widgetPartial;
473 },
474
475 /**
476 * Handles changes to the sidebars_widgets[] setting.
477 *
478 * @since 4.5.0
479 *
480 * @param {Array} newWidgetIds New widget IDs.
481 * @param {Array} oldWidgetIds Old widget IDs.
482 *
483 * @return {void}
484 */
485 handleSettingChange: function( newWidgetIds, oldWidgetIds ) {
486 var sidebarPartial = this, needsRefresh, widgetsRemoved, widgetsAdded, addedWidgetPartials = [];
487
488 needsRefresh = (
489 ( oldWidgetIds.length > 0 && 0 === newWidgetIds.length ) ||
490 ( newWidgetIds.length > 0 && 0 === oldWidgetIds.length )
491 );
492 if ( needsRefresh ) {
493 sidebarPartial.fallback();
494 return;
495 }
496
497 // Handle removal of widgets.
498 widgetsRemoved = _.difference( oldWidgetIds, newWidgetIds );
499 _.each( widgetsRemoved, function( removedWidgetId ) {
500 var widgetPartial = api.selectiveRefresh.partial( 'widget[' + removedWidgetId + ']' );
501 if ( widgetPartial ) {
502 _.each( widgetPartial.placements(), function( placement ) {
503 var isRemoved = (
504 placement.context.sidebar_id === sidebarPartial.sidebarId ||
505 ( placement.context.sidebar_args && placement.context.sidebar_args.id === sidebarPartial.sidebarId )
506 );
507 if ( isRemoved ) {
508 placement.container.remove();
509 }
510 } );
511 }
512 delete self.renderedWidgets[ removedWidgetId ];
513 } );
514
515 // Handle insertion of widgets.
516 widgetsAdded = _.difference( newWidgetIds, oldWidgetIds );
517 _.each( widgetsAdded, function( addedWidgetId ) {
518 var widgetPartial = sidebarPartial.ensureWidgetPlacementContainers( addedWidgetId );
519 addedWidgetPartials.push( widgetPartial );
520 self.renderedWidgets[ addedWidgetId ] = true;
521 } );
522
523 _.each( addedWidgetPartials, function( widgetPartial ) {
524 widgetPartial.refresh();
525 } );
526
527 api.selectiveRefresh.trigger( 'sidebar-updated', sidebarPartial );
528 },
529
530 /**
531 * Refreshes the sidebar partial.
532 *
533 * Note that the meat is handled in handleSettingChange because it has the
534 * context of which widgets were removed.
535 *
536 * @since 4.5.0
537 *
538 * @return {Promise} A promise postponing the refresh.
539 */
540 refresh: function() {
541 var partial = this, deferred = $.Deferred();
542
543 deferred.fail( function() {
544 partial.fallback();
545 } );
546
547 if ( 0 === partial.placements().length ) {
548 deferred.reject();
549 } else {
550 _.each( partial.reflowWidgets(), function( sidebarPlacement ) {
551 api.selectiveRefresh.trigger( 'partial-content-rendered', sidebarPlacement );
552 } );
553 deferred.resolve();
554 }
555
556 return deferred.promise();
557 }
558 });
559
560 api.selectiveRefresh.partialConstructor.sidebar = self.SidebarPartial;
561 api.selectiveRefresh.partialConstructor.widget = self.WidgetPartial;
562
563 /**
564 * Adds partials for the registered widget areas (sidebars).
565 *
566 * @since 4.5.0
567 *
568 * @return {void}
569 */
570 self.addPartials = function() {
571 _.each( self.registeredSidebars, function( registeredSidebar ) {
572 var partial, partialId = 'sidebar[' + registeredSidebar.id + ']';
573 partial = api.selectiveRefresh.partial( partialId );
574 if ( ! partial ) {
575 partial = new self.SidebarPartial( partialId, {
576 params: {
577 sidebarArgs: registeredSidebar
578 }
579 } );
580 api.selectiveRefresh.partial.add( partial );
581 }
582 } );
583 };
584
585 /**
586 * Calculates the selector for the sidebar's widgets based on the registered
587 * sidebar's info.
588 *
589 * @memberOf wp.customize.widgetsPreview
590 *
591 * @since 3.9.0
592 *
593 * @return {void}
594 */
595 self.buildWidgetSelectors = function() {
596 var self = this;
597
598 $.each( self.registeredSidebars, function( i, sidebar ) {
599 var widgetTpl = [
600 sidebar.before_widget,
601 sidebar.before_title,
602 sidebar.after_title,
603 sidebar.after_widget
604 ].join( '' ),
605 emptyWidget,
606 widgetSelector,
607 widgetClasses;
608
609 emptyWidget = $( widgetTpl );
610 widgetSelector = emptyWidget.prop( 'tagName' ) || '';
611 widgetClasses = emptyWidget.prop( 'className' ) || '';
612
613 // Prevent a rare case when before_widget, before_title, after_title and after_widget is empty.
614 if ( ! widgetClasses ) {
615 return;
616 }
617
618 // Remove class names that incorporate the string formatting placeholders %1$s and %2$s.
619 widgetClasses = widgetClasses.replace( /\S*%[12]\$s\S*/g, '' );
620 widgetClasses = widgetClasses.replace( /^\s+|\s+$/g, '' );
621 if ( widgetClasses ) {
622 widgetSelector += '.' + widgetClasses.split( /\s+/ ).join( '.' );
623 }
624 self.widgetSelectors.push( widgetSelector );
625 });
626 };
627
628 /**
629 * Highlights the widget on widget updates or widget control mouse overs.
630 *
631 * @memberOf wp.customize.widgetsPreview
632 *
633 * @since 3.9.0
634 * @param {string} widgetId ID of the widget.
635 *
636 * @return {void}
637 */
638 self.highlightWidget = function( widgetId ) {
639 var $body = $( document.body ),
640 $widget = $( '#' + widgetId );
641
642 $body.find( '.widget-customizer-highlighted-widget' ).removeClass( 'widget-customizer-highlighted-widget' );
643
644 $widget.addClass( 'widget-customizer-highlighted-widget' );
645 setTimeout( function() {
646 $widget.removeClass( 'widget-customizer-highlighted-widget' );
647 }, 500 );
648 };
649
650 /**
651 * Shows a title and highlights widgets on hover. On shift+clicking focuses the
652 * widget control.
653 *
654 * @memberOf wp.customize.widgetsPreview
655 *
656 * @since 3.9.0
657 *
658 * @return {void}
659 */
660 self.highlightControls = function() {
661 var self = this,
662 selector = this.widgetSelectors.join( ',' );
663
664 // Skip adding highlights if not in the customizer preview iframe.
665 if ( ! api.settings.channel ) {
666 return;
667 }
668
669 $( selector ).attr( 'title', this.l10n.widgetTooltip );
670 // Highlights widget when entering the widget editor.
671 $( document ).on( 'mouseenter', selector, function() {
672 self.preview.send( 'highlight-widget-control', $( this ).prop( 'id' ) );
673 });
674
675 // Open expand the widget control when shift+clicking the widget element.
676 $( document ).on( 'click', selector, function( e ) {
677 if ( ! e.shiftKey ) {
678 return;
679 }
680 e.preventDefault();
681
682 self.preview.send( 'focus-widget-control', $( this ).prop( 'id' ) );
683 });
684 };
685
686 /**
687 * Parses a widget ID.
688 *
689 * @memberOf wp.customize.widgetsPreview
690 *
691 * @since 4.5.0
692 *
693 * @param {string} widgetId The widget ID.
694 *
695 * @return {{idBase: string, number: number|null}} An object containing the idBase
696 * and number of the parsed widget ID.
697 */
698 self.parseWidgetId = function( widgetId ) {
699 var matches, parsed = {
700 idBase: '',
701 number: null
702 };
703
704 matches = widgetId.match( /^(.+)-(\d+)$/ );
705 if ( matches ) {
706 parsed.idBase = matches[1];
707 parsed.number = parseInt( matches[2], 10 );
708 } else {
709 parsed.idBase = widgetId; // Likely an old single widget.
710 }
711
712 return parsed;
713 };
714
715 /**
716 * Parses a widget setting ID.
717 *
718 * @memberOf wp.customize.widgetsPreview
719 *
720 * @since 4.5.0
721 *
722 * @param {string} settingId Widget setting ID.
723 *
724 * @return {{idBase: string, number: number|null}|null} Either an object containing the idBase
725 * and number of the parsed widget setting ID,
726 * or null.
727 */
728 self.parseWidgetSettingId = function( settingId ) {
729 var matches, parsed = {
730 idBase: '',
731 number: null
732 };
733
734 matches = settingId.match( /^widget_([^\[]+?)(?:\[(\d+)])?$/ );
735 if ( ! matches ) {
736 return null;
737 }
738 parsed.idBase = matches[1];
739 if ( matches[2] ) {
740 parsed.number = parseInt( matches[2], 10 );
741 }
742 return parsed;
743 };
744
745 /**
746 * Converts a widget ID into a Customizer setting ID.
747 *
748 * @memberOf wp.customize.widgetsPreview
749 *
750 * @since 4.5.0
751 *
752 * @param {string} widgetId The widget ID.
753 *
754 * @return {string} The setting ID.
755 */
756 self.getWidgetSettingId = function( widgetId ) {
757 var parsed = this.parseWidgetId( widgetId ), settingId;
758
759 settingId = 'widget_' + parsed.idBase;
760 if ( parsed.number ) {
761 settingId += '[' + String( parsed.number ) + ']';
762 }
763
764 return settingId;
765 };
766
767 api.bind( 'preview-ready', function() {
768 $.extend( self, _wpWidgetCustomizerPreviewSettings );
769 self.init();
770 });
771
772 return self;
773})( jQuery, _, wp, wp.customize );
774