WordPress.org

Make WordPress Core

Ticket #33503: 33503.6.diff

File 33503.6.diff, 11.2 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..7751304 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 ) {
  • 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..c806170 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 || {}; 
    372404                        return this.add( id, new this.defaultConstructor( api.Class.applicator, slice.call( arguments, 1 ) ) );
    373405                },
    374406
     407                /**
     408                 * Iterate over all items in the collection invoking the provided callback.
     409                 *
     410                 * @param  {Function} callback Function to invoke.
     411                 * @param  {object}   context  Object context to invoke the function with. Optional.
     412                 */
    375413                each: function( callback, context ) {
    376414                        context = typeof context === 'undefined' ? this : context;
    377415
    window.wp = window.wp || {}; 
    458496                }
    459497        });
    460498
     499        // Create a global events bus on the Customizer.
    461500        $.extend( api.Values.prototype, api.Events );
    462501
    463502
    window.wp = window.wp || {}; 
    698737        // Add the Events mixin to api.Messenger.
    699738        $.extend( api.Messenger.prototype, api.Events );
    700739
    701         // Core customize object.
     740        // The main API object is also a collection of all customizer settings.
    702741        api = $.extend( new api.Values(), api );
     742
     743        /**
     744         * Get all settings.
     745         *
     746         * @return {object}
     747         */
    703748        api.get = function() {
    704749                var result = {};
    705750
  • 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,