WordPress.org
Get WordPress

Make WordPress Core

Ticket #33503: 33503.2.diff

File 33503.2.diff, 7.3 KB (added by ericlewis, 10 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..fbc5d16 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':
    … …  
    13471361         * @class
    13481362         * @augments wp.customize.Class
    13491363         *
    1350          * @param {string} id                            Unique identifier for the control instance.
    1351          * @param {object} options                       Options hash for the control instance.
     1364         * @param {string} id                              Unique identifier for the control instance.
     1365         * @param {object} options                         Options hash for the control instance.
    13521366         * @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.
     1367         * @param {object} options.params.type             Type of control (e.g. text, radio, dropdown-pages, etc.)
     1368         * @param {string} options.params.content          The HTML content for the control.
     1369         * @param {string} options.params.priority         Order of priority to show the control within the section.
    13561370         * @param {string} options.params.active
    1357          * @param {string} options.params.section
     1371         * @param {string} options.params.section          The ID of the section the control belongs to.
     1372         * @param {string} options.params.settings.default The ID of the setting the control relates to.
     1373         * @param {string} options.params.settings.data
    13581374         * @param {string} options.params.label
    13591375         * @param {string} options.params.description
    13601376         * @param {string} options.params.instanceNumber Order in which this instance was created in relation to other instances.
    … …  
    14201436
    14211437                        api.utils.bubbleChildValueChanges( control, [ 'section', 'priority', 'active' ] );
    14221438
    1423                         // Associate this control with its settings when they are created
     1439                        // After all settings related to the control are available,
     1440                        // make them available on the control and embed the control into the page.
    14241441                        settings = $.map( control.params.settings, function( value ) {
    14251442                                return value;
    14261443                        });
    … …  
    14371454                                control.embed();
    14381455                        }) );
    14391456
     1457                        // After the control is embedded on the page, invoke the "ready" method.
    14401458                        control.deferred.embedded.done( function () {
    14411459                                control.ready();
    14421460                        });
    … …  
    29282946                        }
    29292947                },
    29302948
     2949                /**
     2950                 * Refresh the preview.
     2951                 */
    29312952                refresh: function() {
    29322953                        var self = this;
    29332954
    … …  
    31373158
    31383159                        nonce: api.settings.nonce,
    31393160
     3161                        /**
     3162                         * Build the query to send along with the Preview request.
     3163                         *
     3164                         * @return {object}
     3165                         */
    31403166                        query: function() {
    31413167                                var dirtyCustomized = {};
    31423168                                api.each( function ( value, key ) {

  • 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..b4b9aca 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 {[type]} 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 add to 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 || {}; 
    698736        // Add the Events mixin to api.Messenger.
    699737        $.extend( api.Messenger.prototype, api.Events );
    700738
    701         // Core customize object.
     739        // The main API object is also a collection of all customizer settings.
    702740        api = $.extend( new api.Values(), api );
     741
     742        /**
     743         * Get all settings.
     744         *
     745         * @return {object}
     746         */
    703747        api.get = function() {
    704748                var result = {};
    705749