diff --git a/src/wp-includes/js/customize-base.js b/src/wp-includes/js/customize-base.js
index db573b5..6c41b40 100644
--- a/src/wp-includes/js/customize-base.js
+++ b/src/wp-includes/js/customize-base.js
@@ -1,25 +1,22 @@
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,12 +62,9 @@ window.wp = window.wp || {};
return child;
};
- api = {};
-
- /* =====================================================================
- * Base class.
- * ===================================================================== */
-
+ /**
+ * Base class for object inheritance.
+ */
api.Class = function( applicator, argsArray, options ) {
var magic, args = arguments;
@@ -92,6 +86,19 @@ window.wp = window.wp || {};
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,12 +123,11 @@ window.wp = window.wp || {};
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,10 +149,11 @@ window.wp = window.wp || {};
}
};
- /* =====================================================================
+ /**
* 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,10 +261,13 @@ window.wp = window.wp || {};
}
});
- /* =====================================================================
+ /**
* A collection of observable values.
- * ===================================================================== */
-
+ *
+ * @constuctor
+ * @augments wp.customize.Class
+ * @mixes wp.customize.Events
+ */
api.Values = api.Class.extend({
defaultConstructor: api.Value,
@@ -379,16 +389,25 @@ window.wp = window.wp || {};
$.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,7 +461,7 @@ window.wp = window.wp || {};
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,13 +492,24 @@ window.wp = window.wp || {};
}
};
- /* =====================================================================
- * 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,10 +600,7 @@ window.wp = window.wp || {};
// 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,6 +612,6 @@ window.wp = window.wp || {};
return result;
};
- // Expose the API to the world.
+ // Expose the API publicly on window.wp.customize
exports.customize = api;
})( wp, jQuery );
diff --git a/src/wp-includes/js/customize-loader.js b/src/wp-includes/js/customize-loader.js
index 98bb32f..2ee0c0f 100644
--- a/src/wp-includes/js/customize-loader.js
+++ b/src/wp-includes/js/customize-loader.js
@@ -10,7 +10,20 @@ window.wp = window.wp || {};
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. Open customizer
+ *
+ * @augments wp.customize.Events
+ */
Loader = $.extend( {}, api.Events, {
+ /**
+ * Setup the Loader; triggered on document#ready.
+ */
initialize: function() {
this.body = $( document.body );
@@ -23,9 +36,12 @@ window.wp = window.wp || {};
this.window = $( window );
this.element = $( '' ).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,6 +89,11 @@ window.wp = window.wp || {};
}
},
+ /**
+ * Open the customizer overlay for a specific URL.
+ *
+ * @param string src URL to load in the Customizer.
+ */
open: function( src ) {
if ( this.active ) {
@@ -148,10 +169,16 @@ window.wp = window.wp || {};
}
},
+ /**
+ * 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,6 +201,9 @@ window.wp = window.wp || {};
}
},
+ /**
+ * Callback after the customizer has been closed.
+ */
closed: function() {
Loader.iframe.remove();
Loader.messenger.destroy();
@@ -184,10 +214,16 @@ window.wp = window.wp || {};
$( 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,11 +235,12 @@ window.wp = window.wp || {};
}
});
+ // 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 );