WordPress.org
Get WordPress

Make WordPress Core

Ticket #29157: 29157.diff

File 29157.diff, 9.5 KB (added by ericlewis, 9 years ago)

  • 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 db573b5..6c41b40 100644
    a b  
    11window.wp = window.wp || {};
    22
    33(function( exports, $ ){
    4         var api, extend, ctor, inherits,
     4        var api = {}, ctor, inherits,
    55                slice = Array.prototype.slice;
    66
    7         /* =====================================================================
    8          * Micro-inheritance - thank you, backbone.js.
    9          * ===================================================================== */
    10 
    11         extend = function( protoProps, classProps ) {
    12                 var child = inherits( this, protoProps, classProps );
    13                 child.extend = this.extend;
    14                 return child;
    15         };
    16 
    177        // Shared empty constructor function to aid in prototype-chain creation.
    188        ctor = function() {};
    199
    20         // Helper function to correctly set up the prototype chain, for subclasses.
    21         // Similar to `goog.inherits`, but uses a hash of prototype properties and
    22         // class properties to be extended.
     10        /**
     11         * Helper function to correctly set up the prototype chain, for subclasses.
     12         * Similar to `goog.inherits`, but uses a hash of prototype properties and
     13         * class properties to be extended.
     14         *
     15         * @param  object parent      Parent class constructor to inherit from.
     16         * @param  object protoProps  Properties to apply to the prototype for use as class instance properties.
     17         * @param  object staticProps Properties to apply directly to the class constructor.
     18         * @return child              The subclassed constructor.
     19         */
    2320        inherits = function( parent, protoProps, staticProps ) {
    2421                var child;
    2522
    … … window.wp = window.wp || {}; 
    6562                return child;
    6663        };
    6764
    68         api = {};
    69 
    70         /* =====================================================================
    71          * Base class.
    72          * ===================================================================== */
    73 
     65        /**
     66         * Base class for object inheritance.
     67         */
    7468        api.Class = function( applicator, argsArray, options ) {
    7569                var magic, args = arguments;
    7670
    … … window.wp = window.wp || {}; 
    9286                return magic;
    9387        };
    9488
     89        /**
     90         * Creates a subclass of the class.
     91         *
     92         * @param  object protoProps  Properties to apply to the prototype.
     93         * @param  object staticProps Properties to apply directly to the class.
     94         * @return child              The subclass.
     95         */
     96        api.Class.extend = function( protoProps, classProps ) {
     97                var child = inherits( this, protoProps, classProps );
     98                child.extend = this.extend;
     99                return child;
     100        };
     101
    95102        api.Class.applicator = {};
    96103
    97104        api.Class.prototype.initialize = function() {};
    … … window.wp = window.wp || {}; 
    116123                return false;
    117124        };
    118125
    119         api.Class.extend = extend;
    120 
    121         /* =====================================================================
    122          * Events mixin.
    123          * ===================================================================== */
    124 
     126        /**
     127         * An events manager object, offering the ability to bind to and trigger events.
     128         *
     129         * Used as a mixin.
     130         */
    125131        api.Events = {
    126132                trigger: function( id ) {
    127133                        if ( this.topics && this.topics[ id ] )
    … … window.wp = window.wp || {}; 
    143149                }
    144150        };
    145151
    146         /* =====================================================================
     152        /**
    147153         * Observable values that support two-way binding.
    148          * ===================================================================== */
    149 
     154         *
     155         * @constuctor
     156         */
    150157        api.Value = api.Class.extend({
    151158                initialize: function( initial, options ) {
    152159                        this._value = initial; // @todo: potentially change this to a this.set() call.
    … … window.wp = window.wp || {}; 
    254261                }
    255262        });
    256263
    257         /* =====================================================================
     264        /**
    258265         * A collection of observable values.
    259          * ===================================================================== */
    260 
     266         *
     267         * @constuctor
     268         * @augments wp.customize.Class
     269         * @mixes wp.customize.Events
     270         */
    261271        api.Values = api.Class.extend({
    262272                defaultConstructor: api.Value,
    263273
    … … window.wp = window.wp || {}; 
    379389
    380390        $.extend( api.Values.prototype, api.Events );
    381391
    382         /* =====================================================================
    383          * An observable value that syncs with an element.
    384          *
    385          * Handles inputs, selects, and textareas by default.
    386          * ===================================================================== */
    387392
     393        /**
     394         * Cast a string to a jQuery collection if it isn't already.
     395         *
     396         * @param {string|jQuery collection} element
     397         */
    388398        api.ensure = function( element ) {
    389399                return typeof element == 'string' ? $( element ) : element;
    390400        };
    391401
     402        /**
     403         * An observable value that syncs with an element.
     404         *
     405         * Handles inputs, selects, and textareas by default.
     406         *
     407         * @constuctor
     408         * @augments wp.customize.Value
     409         * @augments wp.customize.Class
     410         */
    392411        api.Element = api.Value.extend({
    393412                initialize: function( element, options ) {
    394413                        var self = this,
    … … window.wp = window.wp || {}; 
    442461
    443462        api.Element.synchronizer = {};
    444463
    445         $.each( [ 'html', 'val' ], function( i, method ) {
     464        $.each( [ 'html', 'val' ], function( index, method ) {
    446465                api.Element.synchronizer[ method ] = {
    447466                        update: function( to ) {
    448467                                this.element[ method ]( to );
    … … window.wp = window.wp || {}; 
    473492                }
    474493        };
    475494
    476         /* =====================================================================
    477          * Messenger for postMessage.
    478          * ===================================================================== */
    479 
    480495        $.support.postMessage = !! window.postMessage;
    481496
     497        /**
     498         * Messenger for postMessage.
     499         *
     500         * @constuctor
     501         * @augments wp.customize.Class
     502         * @mixes wp.customize.Events
     503         */
    482504        api.Messenger = api.Class.extend({
     505                /**
     506                 * Create a new Value.
     507                 *
     508                 * @param  {string} key     Unique identifier.
     509                 * @param  {mixed}  initial Initial value.
     510                 * @param  {mixed}  options Options hash. Optional.
     511                 * @return {Value}          Class instance of the Value.
     512                 */
    483513                add: function( key, initial, options ) {
    484514                        return this[ key ] = new api.Value( initial, options );
    485515                },
    … … window.wp = window.wp || {}; 
    570600        // Add the Events mixin to api.Messenger.
    571601        $.extend( api.Messenger.prototype, api.Events );
    572602
    573         /* =====================================================================
    574          * Core customize object.
    575          * ===================================================================== */
    576 
     603        // Core customize object.
    577604        api = $.extend( new api.Values(), api );
    578605        api.get = function() {
    579606                var result = {};
    … … window.wp = window.wp || {}; 
    585612                return result;
    586613        };
    587614
    588         // Expose the API to the world.
     615        // Expose the API publicly on window.wp.customize
    589616        exports.customize = api;
    590617})( wp, jQuery );

  • 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 98bb32f..2ee0c0f 100644
    a b window.wp = window.wp || {}; 
    1010                hashchange: ('onhashchange' in window) && (document.documentMode === undefined || document.documentMode > 7)
    1111        });
    1212
     13        /**
     14         * Allows the Customizer to be overlayed on any page.
     15         *
     16         * By default, any element in the body with the load-customize class will open
     17         * the Customizer overlay with the URL specified.
     18         *
     19         *     e.g. <a class="load-customize" href="http://siteurl.com/2014/01/02/post">Open customizer</a>
     20         *
     21         * @augments wp.customize.Events
     22         */
    1323        Loader = $.extend( {}, api.Events, {
     24                /**
     25                 * Setup the Loader; triggered on document#ready.
     26                 */
    1427                initialize: function() {
    1528                        this.body = $( document.body );
    1629
    … … window.wp = window.wp || {}; 
    2336                        this.window  = $( window );
    2437                        this.element = $( '<div id="customize-container" />' ).appendTo( this.body );
    2538
     39                        // Bind events for opening and closing the overlay.
    2640                        this.bind( 'open', this.overlay.show );
    2741                        this.bind( 'close', this.overlay.hide );
    2842
     43                        // Any element in the body with the `load-customize` class opens
     44                        // the Customizer.
    2945                        $('#wpbody').on( 'click', '.load-customize', function( event ) {
    3046                                event.preventDefault();
    3147
    … … window.wp = window.wp || {}; 
    7389                        }
    7490                },
    7591
     92                /**
     93                 * Open the customizer overlay for a specific URL.
     94                 *
     95                 * @param  string src URL to load in the Customizer.
     96                 */
    7697                open: function( src ) {
    7798
    7899                        if ( this.active ) {
    … … window.wp = window.wp || {}; 
    148169                        }
    149170                },
    150171
     172                /**
     173                 * Callback after the customizer has been opened.
     174                 */
    151175                opened: function() {
    152176                        Loader.body.addClass( 'customize-active full-overlay-active' );
    153177                },
    154178
     179                /**
     180                 * Close the Customizer overlay and return focus to the link that opened it.
     181                 */
    155182                close: function() {
    156183                        if ( ! this.active ) {
    157184                                return;
    … … window.wp = window.wp || {}; 
    174201                        }
    175202                },
    176203
     204                /**
     205                 * Callback after the customizer has been closed.
     206                 */
    177207                closed: function() {
    178208                        Loader.iframe.remove();
    179209                        Loader.messenger.destroy();
    … … window.wp = window.wp || {}; 
    184214                        $( window ).off( 'beforeunload', Loader.beforeunload );
    185215                },
    186216
     217                /**
     218                 * Callback for the `load` event on the Customizer iframe.
     219                 */
    187220                loaded: function() {
    188221                        Loader.body.removeClass('customize-loading');
    189222                },
    190223
     224                /**
     225                 * Overlay hide/show utility methods.
     226                 */
    191227                overlay: {
    192228                        show: function() {
    193229                                this.element.fadeIn( 200, Loader.opened );
    … … window.wp = window.wp || {}; 
    199235                }
    200236        });
    201237
     238        // Bootstrap the Loader on document#ready.
    202239        $( function() {
    203240                Loader.settings = _wpCustomizeLoaderSettings;
    204241                Loader.initialize();
    205242        });
    206243
    207         // Expose the API to the world.
     244        // Expose the API publicly on window.wp.customize.Loader
    208245        api.Loader = Loader;
    209246})( wp, jQuery );