WordPress.org

Make WordPress Core

Ticket #33503: 33503.7.diff

File 33503.7.diff, 14.5 KB (added by ericlewis, 5 years ago)
  • src/wp-admin/js/customize-controls.js

    diff --git a/src/wp-admin/js/customize-controls.js b/src/wp-admin/js/customize-controls.js
    index b3b4433..bb1c651 100644
    a b  
    33        var Container, focus, api = wp.customize;
    44
    55        /**
     6         * A Customizer Setting.
     7         *
     8         * A setting is WordPress data (theme mod, option, menu, etc.) that the user can
     9         * draft changes to in the Customizer.
     10         *
     11         * @see PHP class WP_Customize_Setting.
     12         *
    613         * @class
    714         * @augments wp.customize.Value
    815         * @augments wp.customize.Class
    916         *
    10          * @param options
    11          * - previewer - The Previewer instance to sync with.
    12          * - transport - The transport to use for previewing. Supports 'refresh' and 'postMessage'.
     17         * @param {object} id                The Setting ID.
     18         * @param {object} value             The initial value of the setting.
     19         * @param {object} options.previewer The Previewer instance to sync with.
     20         * @param {object} options.transport The transport to use for previewing. Supports 'refresh' and 'postMessage'.
     21         * @param {object} options.dirty
    1322         */
    1423        api.Setting = api.Value.extend({
    1524                initialize: function( id, value, options ) {
     
    1928                        this.transport = this.transport || 'refresh';
    2029                        this._dirty = options.dirty || false;
    2130
     31                        // Whenever the setting's value changes, refresh the preview.
    2232                        this.bind( this.preview );
    2333                },
     34
     35                /**
     36                 * Refresh the preview, respective of the setting's refresh policy.
     37                 */
    2438                preview: function() {
    2539                        switch ( this.transport ) {
    2640                                case 'refresh':
     
    270284                },
    271285
    272286                /**
    273                  * Handle changes to the active state.
     287                 * Active state change handler.
    274288                 *
    275                  * This does not change the active state, it merely handles the behavior
    276                  * for when it does change.
     289                 * Shows the container if it is active, hides it if not.
    277290                 *
    278291                 * To override by subclass, update the container's UI to reflect the provided active state.
    279292                 *
     
    13471360         * @class
    13481361         * @augments wp.customize.Class
    13491362         *
    1350          * @param {string} id                            Unique identifier for the control instance.
    1351          * @param {object} options                       Options hash for the control instance.
     1363         * @param {string} id                              Unique identifier for the control instance.
     1364         * @param {object} options                         Options hash for the control instance.
    13521365         * @param {object} options.params
    1353          * @param {object} options.params.type           Type of control (e.g. text, radio, dropdown-pages, etc.)
    1354          * @param {string} options.params.content        The HTML content for the control.
    1355          * @param {string} options.params.priority       Order of priority to show the control within the section.
     1366         * @param {object} options.params.type             Type of control (e.g. text, radio, dropdown-pages, etc.)
     1367         * @param {string} options.params.content          The HTML content for the control.
     1368         * @param {string} options.params.priority         Order of priority to show the control within the section.
    13561369         * @param {string} options.params.active
    1357          * @param {string} options.params.section
     1370         * @param {string} options.params.section          The ID of the section the control belongs to.
     1371         * @param {string} options.params.settings.default The ID of the setting the control relates to.
     1372         * @param {string} options.params.settings.data
    13581373         * @param {string} options.params.label
    13591374         * @param {string} options.params.description
    13601375         * @param {string} options.params.instanceNumber Order in which this instance was created in relation to other instances.
     
    14201435
    14211436                        api.utils.bubbleChildValueChanges( control, [ 'section', 'priority', 'active' ] );
    14221437
    1423                         // Associate this control with its settings when they are created
     1438                        /*
     1439                         * After all settings related to the control are available,
     1440                         * make them available on the control and embed the control into the page.
     1441                         */
    14241442                        settings = $.map( control.params.settings, function( value ) {
    14251443                                return value;
    14261444                        });
     
    14371455                                control.embed();
    14381456                        }) );
    14391457
     1458                        // After the control is embedded on the page, invoke the "ready" method.
    14401459                        control.deferred.embedded.done( function () {
    14411460                                control.ready();
    14421461                        });
     
    25732592        api.panel = new api.Values({ defaultConstructor: api.Panel });
    25742593
    25752594        /**
     2595         * An object that fetches a preview in the background of the document, which
     2596         * allows for seamless replacement of an existing preview.
     2597         *
    25762598         * @class
    25772599         * @augments wp.customize.Messenger
    25782600         * @augments wp.customize.Class
     
    25812603        api.PreviewFrame = api.Messenger.extend({
    25822604                sensitivity: 2000,
    25832605
     2606                /**
     2607                 * Initialize the PreviewFrame.
     2608                 *
     2609                 * @param {object} params.container
     2610                 * @param {object} params.signature
     2611                 * @param {object} params.previewUrl
     2612                 * @param {object} params.query
     2613                 * @param {object} options
     2614                 */
    25842615                initialize: function( params, options ) {
    25852616                        var deferred = $.Deferred();
    25862617
    2587                         // This is the promise object.
     2618                        /*
     2619                         * Make the instance of the PreviewFrame the promise object
     2620                         * so other objects can easily interact with it.
     2621                         */
    25882622                        deferred.promise( this );
    25892623
    25902624                        this.container = params.container;
     
    26012635                        this.run( deferred );
    26022636                },
    26032637
     2638                /**
     2639                 * Run the preview request.
     2640                 *
     2641                 * @param {object} deferred jQuery Deferred object to be resolved with
     2642                 *                          the request.
     2643                 */
    26042644                run: function( deferred ) {
    26052645                        var self   = this,
    26062646                                loaded = false,
     
    28042844                refreshBuffer: 250,
    28052845
    28062846                /**
    2807                  * Requires params:
    2808                  *  - container  - a selector or jQuery element
    2809                  *  - previewUrl - the URL of preview frame
     2847                 * @param {array}  params.allowedUrls
     2848                 * @param {string} params.container   A selector or jQuery element for the preview
     2849                 *                                    frame to be placed.
     2850                 * @param {string} params.form
     2851                 * @param {string} params.previewUrl  The URL to preview.
     2852                 * @param {string} params.signature
     2853                 * @param {object} options
    28102854                 */
    28112855                initialize: function( params, options ) {
    28122856                        var self = this,
     
    29192963                        } );
    29202964                },
    29212965
     2966                /**
     2967                 * Query string data sent with each preview request.
     2968                 *
     2969                 * @abstract
     2970                 */
    29222971                query: function() {},
    29232972
    29242973                abort: function() {
     
    29282977                        }
    29292978                },
    29302979
     2980                /**
     2981                 * Refresh the preview.
     2982                 */
    29312983                refresh: function() {
    29322984                        var self = this;
    29332985
     
    31373189
    31383190                        nonce: api.settings.nonce,
    31393191
     3192                        /**
     3193                         * Build the query to send along with the Preview request.
     3194                         *
     3195                         * @return {object}
     3196                         */
    31403197                        query: function() {
    31413198                                var dirtyCustomized = {};
    31423199                                api.each( function ( value, key ) {
     
    34643521                        } );
    34653522                }
    34663523
    3467                 // Create a potential postMessage connection with the parent frame.
     3524                /*
     3525                 * Create a postMessage connection with a parent frame,
     3526                 * in case the Customizer frame was opened with the Customize loader.
     3527                 *
     3528                 * @see wp.customize.Loader
     3529                 */
    34683530                parent = new api.Messenger({
    34693531                        url: api.settings.url.parent,
    34703532                        channel: 'loader'
    34713533                });
    34723534
    3473                 // If we receive a 'back' event, we're inside an iframe.
    3474                 // Send any clicks to the 'Return' link to the parent page.
     3535                /*
     3536                 * If we receive a 'back' event, we're inside an iframe.
     3537                 * Send any clicks to the 'Return' link to the parent page.
     3538                 */
    34753539                parent.bind( 'back', function() {
    34763540                        closeBtn.on( 'click.customize-controls-close', function( event ) {
    34773541                                event.preventDefault();
     
    34963560                        });
    34973561                } );
    34983562
    3499                 // When activated, let the loader handle redirecting the page.
    3500                 // If no loader exists, redirect the page ourselves (if a url exists).
     3563                /*
     3564                 * When activated, let the loader handle redirecting the page.
     3565                 * If no loader exists, redirect the page ourselves (if a url exists).
     3566                 */
    35013567                api.bind( 'activated', function() {
    35023568                        if ( parent.targetWindow() )
    35033569                                parent.send( 'activated', api.settings.url.activated );
  • src/wp-includes/class-wp-customize-setting.php

    diff --git a/src/wp-includes/class-wp-customize-setting.php b/src/wp-includes/class-wp-customize-setting.php
    index d007965..98f37f9 100644
    a b class WP_Customize_Setting { 
    2424        public $manager;
    2525
    2626        /**
     27         * Unique string identifier for the setting.
     28         *
    2729         * @access public
    2830         * @var string
    2931         */
    class WP_Customize_Setting { 
    7476         */
    7577        public $dirty = false;
    7678
     79        /**
     80         * @var array
     81         */
    7782        protected $id_data = array();
    7883
    7984        /**
    class WP_Customize_Setting { 
    148153        protected $_original_value;
    149154
    150155        /**
    151          * Handle previewing the setting.
     156         * Set up filters for the setting so that the preview request
     157         * will render the drafted changes.
    152158         *
    153159         * @since 3.4.0
    154160         */
  • src/wp-includes/js/customize-base.js

    diff --git a/src/wp-includes/js/customize-base.js b/src/wp-includes/js/customize-base.js
    index 720a312..79ba464 100644
    a b window.wp = window.wp || {}; 
    7878                /*
    7979                 * If the class has a method called "instance",
    8080                 * the return value from the class' constructor will be a function that
    81                  * calls invoked, along with all the object properties of the class.
     81                 * calls the "instance" method.
     82                 *
     83                 * It is also an object that has properties and methods inside it.
    8284                 */
    8385                if ( this.instance ) {
    8486                        magic = function() {
    window.wp = window.wp || {}; 
    166168         * @constuctor
    167169         */
    168170        api.Value = api.Class.extend({
     171                /**
     172                 * @param {mixed}  initial The initial value.
     173                 * @param {object} options
     174                 */
    169175                initialize: function( initial, options ) {
    170176                        this._value = initial; // @todo: potentially change this to a this.set() call.
    171177                        this.callbacks = $.Callbacks();
    window.wp = window.wp || {}; 
    184190                        return arguments.length ? this.set.apply( this, arguments ) : this.get();
    185191                },
    186192
     193                /**
     194                 * Get the value.
     195                 *
     196                 * @return {mixed}
     197                 */
    187198                get: function() {
    188199                        return this._value;
    189200                },
    190201
     202                /**
     203                 * Set the value and trigger all bound callbacks.
     204                 *
     205                 * @param {object} to New value.
     206                 */
    191207                set: function( to ) {
    192208                        var from = this._value;
    193209
    window.wp = window.wp || {}; 
    230246                        return value;
    231247                },
    232248
     249                /**
     250                 * Bind a function to be invoked whenever the value changes.
     251                 *
     252                 * @param {...Function} A function, or multiple functions, to add to the callback stack.
     253                 */
    233254                bind: function() {
    234255                        this.callbacks.add.apply( this.callbacks, arguments );
    235256                        return this;
    236257                },
    237258
     259                /**
     260                 * Unbind a previously bound function.
     261                 *
     262                 * @param {...Function} A function, or multiple functions, to remove from the callback stack.
     263                 */
    238264                unbind: function() {
    239265                        this.callbacks.remove.apply( this.callbacks, arguments );
    240266                        return this;
    window.wp = window.wp || {}; 
    283309         * @mixes wp.customize.Events
    284310         */
    285311        api.Values = api.Class.extend({
     312
     313                /**
     314                 * The default constructor for items of the collection.
     315                 *
     316                 * @type {object}
     317                 */
    286318                defaultConstructor: api.Value,
    287319
    288320                initialize: function( options ) {
    window.wp = window.wp || {}; 
    347379
    348380                        this._value[ id ] = value;
    349381                        value.parent = this;
     382
     383                        // Propagate a 'change' event on an item up to the collection.
    350384                        if ( value.extended( api.Value ) )
    351385                                value.bind( this._change );
    352386
    window.wp = window.wp || {}; 
    372406                        return this.add( id, new this.defaultConstructor( api.Class.applicator, slice.call( arguments, 1 ) ) );
    373407                },
    374408
     409                /**
     410                 * Iterate over all items in the collection invoking the provided callback.
     411                 *
     412                 * @param  {Function} callback Function to invoke.
     413                 * @param  {object}   context  Object context to invoke the function with. Optional.
     414                 */
    375415                each: function( callback, context ) {
    376416                        context = typeof context === 'undefined' ? this : context;
    377417
    window.wp = window.wp || {}; 
    453493                        return dfd.promise();
    454494                },
    455495
     496                /**
     497                 * A helper function to propagate a 'change' event from an item
     498                 * to the collection itself.
     499                 */
    456500                _change: function() {
    457501                        this.parent.trigger( 'change', this );
    458502                }
    459503        });
    460504
     505        // Create a global events bus on the Customizer.
    461506        $.extend( api.Values.prototype, api.Events );
    462507
    463508
    window.wp = window.wp || {}; 
    570615        $.support.postMessage = !! window.postMessage;
    571616
    572617        /**
    573          * Messenger for postMessage.
     618         * A communicator for sending data from one window to another over postMessage.
    574619         *
    575620         * @constuctor
    576621         * @augments wp.customize.Class
    window.wp = window.wp || {}; 
    649694                        $( window ).off( 'message', this.receive );
    650695                },
    651696
     697                /**
     698                 * Receive data from the other window.
     699                 *
     700                 * @param  {jQuery.Event} event Event with embedded data.
     701                 */
    652702                receive: function( event ) {
    653703                        var message;
    654704
    window.wp = window.wp || {}; 
    679729                        this.trigger( message.id, message.data );
    680730                },
    681731
     732                /**
     733                 * Send data to the other window.
     734                 *
     735                 * @param  {string} id   The event name.
     736                 * @param  {object} data Data.
     737                 */
    682738                send: function( id, data ) {
    683739                        var message;
    684740
    window.wp = window.wp || {}; 
    698754        // Add the Events mixin to api.Messenger.
    699755        $.extend( api.Messenger.prototype, api.Events );
    700756
    701         // Core customize object.
     757        // The main API object is also a collection of all customizer settings.
    702758        api = $.extend( new api.Values(), api );
     759
     760        /**
     761         * Get all customize settings.
     762         *
     763         * @return {object}
     764         */
    703765        api.get = function() {
    704766                var result = {};
    705767
  • src/wp-includes/js/customize-loader.js

    diff --git a/src/wp-includes/js/customize-loader.js b/src/wp-includes/js/customize-loader.js
    index 5bc34c4..f853f37 100644
    a b window.wp = window.wp || {}; 
    115115                        this.active = true;
    116116                        this.body.addClass('customize-loading');
    117117
    118                         // Dirty state of Customizer in iframe
     118                        /*
     119                         * Track the dirtiness state (whether the drafted changes have been published)
     120                         * of the Customizer in the iframe. This is used to decide whether to display
     121                         * an AYS alert if the user tries to close the window before saving changes.
     122                         */
    119123                        this.saved = new api.Value( true );
    120124
    121125                        this.iframe = $( '<iframe />', { 'src': src, 'title': Loader.settings.l10n.mainIframeTitle } ).appendTo( this.element );
  • src/wp-includes/js/customize-preview.js

    diff --git a/src/wp-includes/js/customize-preview.js b/src/wp-includes/js/customize-preview.js
    index 7cea7d3..29341d7 100644
    a b  
    111111                        api.preview.send( 'documentTitle', document.title );
    112112                });
    113113
     114                /*
     115                 * Send a message to the parent customize frame with a list of which
     116                 * containers and controls are active.
     117                 */
    114118                api.preview.send( 'ready', {
    115119                        activePanels: api.settings.activePanels,
    116120                        activeSections: api.settings.activeSections,