Ticket #29157: 29157.diff

src/wp-includes/js/customize-base.js

@@ -1 +1 @@
 window.wp = window.wp || {};
 
 (function( exports, $ ){
-        var api, extend, ctor, inherits,
+        var api = {}, ctor, inherits,
                 slice = Array.prototype.slice;
 
-        /* =====================================================================
-         * Micro-inheritance - thank you, backbone.js.
-         * ===================================================================== */
-
-        extend = function( protoProps, classProps ) {
-                var child = inherits( this, protoProps, classProps );
-                child.extend = this.extend;
-                return child;
-        };
-
         // Shared empty constructor function to aid in prototype-chain creation.
         ctor = function() {};
 
-        // Helper function to correctly set up the prototype chain, for subclasses.
-        // Similar to `goog.inherits`, but uses a hash of prototype properties and
-        // class properties to be extended.
+        /**
+         * Helper function to correctly set up the prototype chain, for subclasses.
+         * Similar to `goog.inherits`, but uses a hash of prototype properties and
+         * class properties to be extended.
+         *
+         * @param  object parent      Parent class constructor to inherit from.
+         * @param  object protoProps  Properties to apply to the prototype for use as class instance properties.
+         * @param  object staticProps Properties to apply directly to the class constructor.
+         * @return child              The subclassed constructor.
+         */
         inherits = function( parent, protoProps, staticProps ) {
                 var child;
 
@@ -65 +62 @@
                 return child;
         };
 
-        api = {};
-
-        /* =====================================================================
-         * Base class.
-         * ===================================================================== */
-
+        /**
+         * Base class for object inheritance.
+         */
         api.Class = function( applicator, argsArray, options ) {
                 var magic, args = arguments;
 
@@ -92 +86 @@
                 return magic;
         };
 
+        /**
+         * Creates a subclass of the class.
+         *
+         * @param  object protoProps  Properties to apply to the prototype.
+         * @param  object staticProps Properties to apply directly to the class.
+         * @return child              The subclass.
+         */
+        api.Class.extend = function( protoProps, classProps ) {
+                var child = inherits( this, protoProps, classProps );
+                child.extend = this.extend;
+                return child;
+        };
+
         api.Class.applicator = {};
 
         api.Class.prototype.initialize = function() {};
@@ -116 +123 @@
                 return false;
         };
 
-        api.Class.extend = extend;
-
-        /* =====================================================================
-         * Events mixin.
-         * ===================================================================== */
-
+        /**
+         * An events manager object, offering the ability to bind to and trigger events.
+         *
+         * Used as a mixin.
+         */
         api.Events = {
                 trigger: function( id ) {
                         if ( this.topics && this.topics[ id ] )
@@ -143 +149 @@
                 }
         };
 
-        /* =====================================================================
+        /**
          * Observable values that support two-way binding.
-         * ===================================================================== */
-
+         *
+         * @constuctor
+         */
         api.Value = api.Class.extend({
                 initialize: function( initial, options ) {
                         this._value = initial; // @todo: potentially change this to a this.set() call.
@@ -254 +261 @@
                 }
         });
 
-        /* =====================================================================
+        /**
          * A collection of observable values.
-         * ===================================================================== */
-
+         *
+         * @constuctor
+         * @augments wp.customize.Class
+         * @mixes wp.customize.Events
+         */
         api.Values = api.Class.extend({
                 defaultConstructor: api.Value,
 
@@ -379 +389 @@
 
         $.extend( api.Values.prototype, api.Events );
 
-        /* =====================================================================
-         * An observable value that syncs with an element.
-         *
-         * Handles inputs, selects, and textareas by default.
-         * ===================================================================== */
 
+        /**
+         * Cast a string to a jQuery collection if it isn't already.
+         *
+         * @param {string|jQuery collection} element
+         */
         api.ensure = function( element ) {
                 return typeof element == 'string' ? $( element ) : element;
         };
 
+        /**
+         * An observable value that syncs with an element.
+         *
+         * Handles inputs, selects, and textareas by default.
+         *
+         * @constuctor
+         * @augments wp.customize.Value
+         * @augments wp.customize.Class
+         */
         api.Element = api.Value.extend({
                 initialize: function( element, options ) {
                         var self = this,
@@ -442 +461 @@
 
         api.Element.synchronizer = {};
 
-        $.each( [ 'html', 'val' ], function( i, method ) {
+        $.each( [ 'html', 'val' ], function( index, method ) {
                 api.Element.synchronizer[ method ] = {
                         update: function( to ) {
                                 this.element[ method ]( to );
@@ -473 +492 @@
                 }
         };
 
-        /* =====================================================================
-         * Messenger for postMessage.
-         * ===================================================================== */
-
         $.support.postMessage = !! window.postMessage;
 
+        /**
+         * Messenger for postMessage.
+         *
+         * @constuctor
+         * @augments wp.customize.Class
+         * @mixes wp.customize.Events
+         */
         api.Messenger = api.Class.extend({
+                /**
+                 * Create a new Value.
+                 *
+                 * @param  {string} key     Unique identifier.
+                 * @param  {mixed}  initial Initial value.
+                 * @param  {mixed}  options Options hash. Optional.
+                 * @return {Value}          Class instance of the Value.
+                 */
                 add: function( key, initial, options ) {
                         return this[ key ] = new api.Value( initial, options );
                 },
@@ -570 +600 @@
         // Add the Events mixin to api.Messenger.
         $.extend( api.Messenger.prototype, api.Events );
 
-        /* =====================================================================
-         * Core customize object.
-         * ===================================================================== */
-
+        // Core customize object.
         api = $.extend( new api.Values(), api );
         api.get = function() {
                 var result = {};
@@ -585 +612 @@
                 return result;
         };
 
-        // Expose the API to the world.
+        // Expose the API publicly on window.wp.customize
         exports.customize = api;
 })( wp, jQuery );

src/wp-includes/js/customize-loader.js

@@ -10 +10 @@
                 hashchange: ('onhashchange' in window) && (document.documentMode === undefined || document.documentMode > 7)
         });
 
+        /**
+         * Allows the Customizer to be overlayed on any page.
+         *
+         * By default, any element in the body with the load-customize class will open
+         * the Customizer overlay with the URL specified.
+         *
+         *     e.g. <a class="load-customize" href="http://siteurl.com/2014/01/02/post">Open customizer</a>
+         *
+         * @augments wp.customize.Events
+         */
         Loader = $.extend( {}, api.Events, {
+                /**
+                 * Setup the Loader; triggered on document#ready.
+                 */
                 initialize: function() {
                         this.body = $( document.body );
 
@@ -23 +36 @@
                         this.window  = $( window );
                         this.element = $( '<div id="customize-container" />' ).appendTo( this.body );
 
+                        // Bind events for opening and closing the overlay.
                         this.bind( 'open', this.overlay.show );
                         this.bind( 'close', this.overlay.hide );
 
+                        // Any element in the body with the `load-customize` class opens
+                        // the Customizer.
                         $('#wpbody').on( 'click', '.load-customize', function( event ) {
                                 event.preventDefault();
 
@@ -73 +89 @@
                         }
                 },
 
+                /**
+                 * Open the customizer overlay for a specific URL.
+                 *
+                 * @param  string src URL to load in the Customizer.
+                 */
                 open: function( src ) {
 
                         if ( this.active ) {
@@ -148 +169 @@
                         }
                 },
 
+                /**
+                 * Callback after the customizer has been opened.
+                 */
                 opened: function() {
                         Loader.body.addClass( 'customize-active full-overlay-active' );
                 },
 
+                /**
+                 * Close the Customizer overlay and return focus to the link that opened it.
+                 */
                 close: function() {
                         if ( ! this.active ) {
                                 return;
@@ -174 +201 @@
                         }
                 },
 
+                /**
+                 * Callback after the customizer has been closed.
+                 */
                 closed: function() {
                         Loader.iframe.remove();
                         Loader.messenger.destroy();
@@ -184 +214 @@
                         $( window ).off( 'beforeunload', Loader.beforeunload );
                 },
 
+                /**
+                 * Callback for the `load` event on the Customizer iframe.
+                 */
                 loaded: function() {
                         Loader.body.removeClass('customize-loading');
                 },
 
+                /**
+                 * Overlay hide/show utility methods.
+                 */
                 overlay: {
                         show: function() {
                                 this.element.fadeIn( 200, Loader.opened );
@@ -199 +235 @@
                 }
         });
 
+        // Bootstrap the Loader on document#ready.
         $( function() {
                 Loader.settings = _wpCustomizeLoaderSettings;
                 Loader.initialize();
         });
 
-        // Expose the API to the world.
+        // Expose the API publicly on window.wp.customize.Loader
         api.Loader = Loader;
 })( wp, jQuery );