Make WordPress Core

Changeset 29450


Ignore:
Timestamp:
08/08/2014 10:09:46 PM (11 years ago)
Author:
wonderboymusic
Message:

Add some docs to Customizer JS.

Props ericlewis.
See #29157.

Location:
trunk/src/wp-includes/js
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/js/customize-base.js

    r26702 r29450  
    22
    33(function( exports, $ ){
    4     var api, extend, ctor, inherits,
     4    var api = {}, ctor, inherits,
    55        slice = Array.prototype.slice;
    6 
    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     };
    166
    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;
     
    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;
     
    9185        magic.initialize.apply( magic, args );
    9286        return magic;
     87    };
     88
     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;
    93100    };
    94101
     
    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 ) {
     
    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 ) {
     
    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,
     
    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      * ===================================================================== */
    387 
     392
     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 ) {
     
    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 ) {
     
    474493    };
    475494
    476     /* =====================================================================
     495    $.support.postMessage = !! window.postMessage;
     496
     497    /**
    477498     * Messenger for postMessage.
    478      * ===================================================================== */
    479 
    480     $.support.postMessage = !! window.postMessage;
    481 
     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 );
     
    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() {
     
    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 );
  • trunk/src/wp-includes/js/customize-loader.js

    r29025 r29450  
    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 );
     
    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();
     
    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
     
    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 ) {
     
    175202        },
    176203
     204        /**
     205         * Callback after the customizer has been closed.
     206         */
    177207        closed: function() {
    178208            Loader.iframe.remove();
     
    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() {
     
    200236    });
    201237
     238    // Bootstrap the Loader on document#ready.
    202239    $( function() {
    203240        Loader.settings = _wpCustomizeLoaderSettings;
     
    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 );
Note: See TracChangeset for help on using the changeset viewer.