![(please configure the [header_logo] section in trac.ini)](/chrome/site/your_project_logo.png){kind=logo}
Changeset 42416
- Timestamp:
- 12/21/2017 03:11:25 PM (9 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/wp-includes/js/customize-preview-widgets.js
r41872 r42416 1 1 /* global _wpWidgetCustomizerPreviewSettings */ 2 2 3 /** @namespace wp.customize.widgetsPreview */ 3 /** 4 * Handles the initialization, refreshing and rendering of widget partials and sidebar widgets. 5 * 6 * @since 4.5.0 7 * 8 * @namespace wp.customize.widgetsPreview 9 * 10 * @param {jQuery} $ The jQuery object. 11 * @param {Object} _ The utilities library. 12 * @param {Object} wp Current WordPress environment instance. 13 * @param {Object} api Information from the API. 14 * 15 * @returns {Object} Widget-related variables. 16 */ 4 17 wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function( $, _, wp, api ) { 5 18 … … 20 33 21 34 /** 22 * Init widgets preview.35 * Initializes the widgets preview. 23 36 * 24 37 * @since 4.5.0 38 * 39 * @memberOf wp.customize.widgetsPreview 40 * 41 * @returns {void} 25 42 */ 26 43 self.init = function() { … … 60 77 }; 61 78 62 /**63 * Partial representing a widget instance.64 *65 * @memberOf wp.customize.widgetsPreview66 * @alias wp.customize.widgetsPreview.WidgetPartial67 *68 * @class69 * @augments wp.customize.selectiveRefresh.Partial70 * @since 4.5.071 */72 79 self.WidgetPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.WidgetPartial.prototype */{ 73 80 74 81 /** 75 * Constructor. 76 * 77 * @since 4.5.0 78 * @param {string} id - Partial ID. 79 * @param {Object} options 80 * @param {Object} options.params 82 * Represents a partial widget instance. 83 * 84 * @since 4.5.0 85 * 86 * @constructs 87 * @augments wp.customize.selectiveRefresh.Partial 88 * 89 * @alias wp.customize.widgetsPreview.WidgetPartial 90 * @memberOf wp.customize.widgetsPreview 91 * 92 * @param {string} id The partial's ID. 93 * @param {Object} options Options used to initialize the partial's 94 * instance. 95 * @param {Object} options.params The options parameters. 81 96 */ 82 97 initialize: function( id, options ) { … … 102 117 103 118 /** 104 * Refresh widget partial. 105 * 106 * @returns {Promise} 119 * Refreshes the widget partial. 120 * 121 * @since 4.5.0 122 * 123 * @returns {Promise|void} Either a promise postponing the refresh, or void. 107 124 */ 108 125 refresh: function() { … … 119 136 120 137 /** 121 * Send widget-updated message to parent so spinner will get removed from widget control. 122 * 123 * @inheritdoc 124 * @param {wp.customize.selectiveRefresh.Placement} placement 138 * Sends the widget-updated message to the parent so the spinner will get 139 * removed from the widget control. 140 * 141 * @inheritDoc 142 * @param {wp.customize.selectiveRefresh.Placement} placement The placement 143 * function. 144 * 145 * @returns {void} 125 146 */ 126 147 renderContent: function( placement ) { … … 133 154 }); 134 155 135 /**136 * Partial representing a widget area.137 *138 * @memberOf wp.customize.widgetsPreview139 * @alias wp.customize.widgetsPreview.SidebarPartial140 *141 * @class142 * @augments wp.customize.selectiveRefresh.Partial143 * @since 4.5.0144 */145 156 self.SidebarPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.SidebarPartial.prototype */{ 146 157 147 158 /** 148 * Constructor. 149 * 150 * @since 4.5.0 151 * @param {string} id - Partial ID. 152 * @param {Object} options 153 * @param {Object} options.params 159 * Represents a partial widget area. 160 * 161 * @since 4.5.0 162 * 163 * @class 164 * @augments wp.customize.selectiveRefresh.Partial 165 * 166 * @memberOf wp.customize.widgetsPreview 167 * @alias wp.customize.widgetsPreview.SidebarPartial 168 * 169 * @param {string} id The partial's ID. 170 * @param {Object} options Options used to initialize the partial's instance. 171 * @param {Object} options.params The options parameters. 154 172 */ 155 173 initialize: function( id, options ) { … … 180 198 181 199 /** 182 * Set up the partial. 183 * 184 * @since 4.5.0 200 * Sets up the partial. 201 * 202 * @since 4.5.0 203 * 204 * @returns {void} 185 205 */ 186 206 ready: function() { … … 221 241 222 242 /** 223 * Get the before/after boundary nodes for all instances of this sidebar (usually one). 243 * Gets the before/after boundary nodes for all instances of this sidebar 244 * (usually one). 224 245 * 225 246 * Note that TreeWalker is not implemented in IE8. 226 247 * 227 248 * @since 4.5.0 249 * 228 250 * @returns {Array.<{before: Comment, after: Comment, instanceNumber: number}>} 251 * An array with an object for each sidebar instance, containing the 252 * node before and after the sidebar instance and its instance number. 229 253 */ 230 254 findDynamicSidebarBoundaryNodes: function() { … … 262 286 263 287 /** 264 * Get the placements for this partial. 265 * 266 * @since 4.5.0 267 * @returns {Array} 288 * Gets the placements for this partial. 289 * 290 * @since 4.5.0 291 * 292 * @returns {Array} An array containing placement objects for each of the 293 * dynamic sidebar boundary nodes. 268 294 */ 269 295 placements: function() { … … 287 313 * @since 4.5.0 288 314 * 289 * @returns {Array} 315 * @throws {Error} If there's no settingId. 316 * @throws {Error} If the setting doesn't exist in the API. 317 * @throws {Error} If the API doesn't pass an array of widget ids. 318 * 319 * @returns {Array} A shallow copy of the array containing widget IDs. 290 320 */ 291 321 getWidgetIds: function() { … … 306 336 307 337 /** 308 * Reflow widgets in the sidebar, ensuring they have the proper position in the DOM. 309 * 310 * @since 4.5.0 311 * 312 * @return {Array.<wp.customize.selectiveRefresh.Placement>} List of placements that were reflowed. 338 * Reflows widgets in the sidebar, ensuring they have the proper position in the 339 * DOM. 340 * 341 * @since 4.5.0 342 * 343 * @returns {Array.<wp.customize.selectiveRefresh.Placement>} List of placements 344 * that were reflowed. 313 345 */ 314 346 reflowWidgets: function() { … … 370 402 371 403 /** 372 * Make sure there is a widget instance container in this sidebar for the given widget ID. 373 * 374 * @since 4.5.0 375 * 376 * @param {string} widgetId 377 * @returns {wp.customize.selectiveRefresh.Partial} Widget instance partial. 404 * Makes sure there is a widget instance container in this sidebar for the given 405 * widget ID. 406 * 407 * @since 4.5.0 408 * 409 * @param {string} widgetId The widget ID. 410 * 411 * @returns {wp.customize.selectiveRefresh.Partial} The widget instance partial. 378 412 */ 379 413 ensureWidgetPlacementContainers: function( widgetId ) { … … 436 470 437 471 /** 438 * Handle change to the sidebars_widgets[] setting. 439 * 440 * @since 4.5.0 441 * 442 * @param {Array} newWidgetIds New widget ids. 443 * @param {Array} oldWidgetIds Old widget ids. 472 * Handles changes to the sidebars_widgets[] setting. 473 * 474 * @since 4.5.0 475 * 476 * @param {Array} newWidgetIds New widget IDs. 477 * @param {Array} oldWidgetIds Old widget IDs. 478 * 479 * @returns {void} 444 480 */ 445 481 handleSettingChange: function( newWidgetIds, oldWidgetIds ) { … … 489 525 490 526 /** 491 * Note that the meat is handled in handleSettingChange because it has the context of which widgets were removed. 492 * 493 * @since 4.5.0 527 * Refreshes the sidebar partial. 528 * 529 * Note that the meat is handled in handleSettingChange because it has the 530 * context of which widgets were removed. 531 * 532 * @since 4.5.0 533 * 534 * @returns {Promise} A promise postponing the refresh. 494 535 */ 495 536 refresh: function() { … … 517 558 518 559 /** 519 * Add partials for the registered widget areas (sidebars).560 * Adds partials for the registered widget areas (sidebars). 520 561 * 521 562 * @since 4.5.0 563 * 564 * @returns {void} 522 565 */ 523 566 self.addPartials = function() { … … 537 580 538 581 /** 539 * Calculate the selector for the sidebar's widgets based on the registered sidebar's info. 582 * Calculates the selector for the sidebar's widgets based on the registered 583 * sidebar's info. 540 584 * 541 585 * @memberOf wp.customize.widgetsPreview 542 586 * 543 587 * @since 3.9.0 588 * 589 * @returns {void} 544 590 */ 545 591 self.buildWidgetSelectors = function() { … … 577 623 578 624 /** 579 * Highlight the widget on widget updates or widget control mouse overs.625 * Highlights the widget on widget updates or widget control mouse overs. 580 626 * 581 627 * @memberOf wp.customize.widgetsPreview … … 583 629 * @since 3.9.0 584 630 * @param {string} widgetId ID of the widget. 631 * 632 * @returns {void} 585 633 */ 586 634 self.highlightWidget = function( widgetId ) { … … 597 645 598 646 /** 599 * Show a title and highlight widgets on hover. On shift+clicking600 * focus thewidget control.647 * Shows a title and highlights widgets on hover. On shift+clicking focuses the 648 * widget control. 601 649 * 602 650 * @memberOf wp.customize.widgetsPreview 603 651 * 604 652 * @since 3.9.0 653 * 654 * @returns {void} 605 655 */ 606 656 self.highlightControls = function() { … … 614 664 615 665 $( selector ).attr( 'title', this.l10n.widgetTooltip ); 616 666 // Highlights widget when entering the widget editor. 617 667 $( document ).on( 'mouseenter', selector, function() { 618 668 self.preview.send( 'highlight-widget-control', $( this ).prop( 'id' ) ); … … 631 681 632 682 /** 633 * Parse a widget ID.683 * Parses a widget ID. 634 684 * 635 685 * @memberOf wp.customize.widgetsPreview … … 637 687 * @since 4.5.0 638 688 * 639 * @param {string} widgetId Widget ID. 640 * @returns {{idBase: string, number: number|null}} 689 * @param {string} widgetId The widget ID. 690 * 691 * @returns {{idBase: string, number: number|null}} An object containing the 692 * idBase and number of the parsed widget ID. 641 693 */ 642 694 self.parseWidgetId = function( widgetId ) { … … 658 710 659 711 /** 660 * Parse a widget setting ID.712 * Parses a widget setting ID. 661 713 * 662 714 * @memberOf wp.customize.widgetsPreview … … 665 717 * 666 718 * @param {string} settingId Widget setting ID. 667 * @returns {{idBase: string, number: number|null}|null} 719 * 720 * @returns {{idBase: string, number: number|null}|null} Either an object 721 * containing the idBase and number of the parsed widget setting ID, or 722 * null. 668 723 */ 669 724 self.parseWidgetSettingId = function( settingId ) { … … 685 740 686 741 /** 687 * Convert a widget ID into a Customizer setting ID.742 * Converts a widget ID into a Customizer setting ID. 688 743 * 689 744 * @memberOf wp.customize.widgetsPreview … … 691 746 * @since 4.5.0 692 747 * 693 * @param {string} widgetId Widget ID. 694 * @returns {string} settingId Setting ID. 748 * @param {string} widgetId The widget ID. 749 * 750 * @returns {string} The setting ID. 695 751 */ 696 752 self.getWidgetSettingId = function( widgetId ) {
Note:
See TracChangeset
for help on using the changeset viewer.
