WordPress.org
Get WordPress

Make WordPress Core

Changeset 33911


Ignore:
Timestamp:
09/05/2015 07:52:17 PM (8 years ago)
Author:
wonderboymusic
Message:

Add Customizer docs.

Props ericlewis.
See #33503.

Location:
trunk/src
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/js/customize-controls.js

    r33902 r33911  
    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({
    … …  
    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 ) {
    … …  
    271285
    272286        /**
    273          * Handle changes to the active state.
    274          *
    275          * This does not change the active state, it merely handles the behavior
    276          * for when it does change.
     287         * Active state change handler.
     288         *
     289         * Shows the container if it is active, hides it if not.
    277290         *
    278291         * To override by subclass, update the container's UI to reflect the provided active state.
    … …  
    13481361     * @augments wp.customize.Class
    13491362     *
    1350      * @param {string} id                            Unique identifier for the control instance.
    1351      * @param {object} options                       Options hash for the control instance.
     1363     * @param {string} id                              Unique identifier for the control instance.
     1364     * @param {object} options                         Options hash for the control instance.
    13521365     * @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.
     1366     * @param {object} options.params.type             Type of control (e.g. text, radio, dropdown-pages, etc.)
     1367     * @param {string} options.params.content          The HTML content for the control.
     1368     * @param {string} options.params.priority         Order of priority to show the control within the section.
    13561369     * @param {string} options.params.active
    1357      * @param {string} options.params.section
     1370     * @param {string} options.params.section          The ID of the section the control belongs to.
     1371     * @param {string} options.params.settings.default The ID of the setting the control relates to.
     1372     * @param {string} options.params.settings.data
    13581373     * @param {string} options.params.label
    13591374     * @param {string} options.params.description
    … …  
    14211436            api.utils.bubbleChildValueChanges( control, [ 'section', 'priority', 'active' ] );
    14221437
    1423             // Associate this control with its settings when they are created
     1438            /*
     1439             * After all settings related to the control are available,
     1440             * make them available on the control and embed the control into the page.
     1441             */
    14241442            settings = $.map( control.params.settings, function( value ) {
    14251443                return value;
    … …  
    14381456            }) );
    14391457
     1458            // After the control is embedded on the page, invoke the "ready" method.
    14401459            control.deferred.embedded.done( function () {
    14411460                control.ready();
    … …  
    25742593
    25752594    /**
     2595     * An object that fetches a preview in the background of the document, which
     2596     * allows for seamless replacement of an existing preview.
     2597     *
    25762598     * @class
    25772599     * @augments wp.customize.Messenger
    … …  
    25822604        sensitivity: 2000,
    25832605
     2606        /**
     2607         * Initialize the PreviewFrame.
     2608         *
     2609         * @param {object} params.container
     2610         * @param {object} params.signature
     2611         * @param {object} params.previewUrl
     2612         * @param {object} params.query
     2613         * @param {object} options
     2614         */
    25842615        initialize: function( params, options ) {
    25852616            var deferred = $.Deferred();
    25862617
    2587             // This is the promise object.
     2618            /*
     2619             * Make the instance of the PreviewFrame the promise object
     2620             * so other objects can easily interact with it.
     2621             */
    25882622            deferred.promise( this );
    25892623
    … …  
    26022636        },
    26032637
     2638        /**
     2639         * Run the preview request.
     2640         *
     2641         * @param {object} deferred jQuery Deferred object to be resolved with
     2642         *                          the request.
     2643         */
    26042644        run: function( deferred ) {
    26052645            var self   = this,
    … …  
    28052845
    28062846        /**
    2807          * Requires params:
    2808          *  - container  - a selector or jQuery element
    2809          *  - previewUrl - the URL of preview frame
     2847         * @param {array}  params.allowedUrls
     2848         * @param {string} params.container   A selector or jQuery element for the preview
     2849         *                                    frame to be placed.
     2850         * @param {string} params.form
     2851         * @param {string} params.previewUrl  The URL to preview.
     2852         * @param {string} params.signature
     2853         * @param {object} options
    28102854         */
    28112855        initialize: function( params, options ) {
    … …  
    29202964        },
    29212965
     2966        /**
     2967         * Query string data sent with each preview request.
     2968         *
     2969         * @abstract
     2970         */
    29222971        query: function() {},
    29232972
    … …  
    29292978        },
    29302979
     2980        /**
     2981         * Refresh the preview.
     2982         */
    29312983        refresh: function() {
    29322984            var self = this;
    … …  
    31413193            nonce: api.settings.nonce,
    31423194
     3195            /**
     3196             * Build the query to send along with the Preview request.
     3197             *
     3198             * @return {object}
     3199             */
    31433200            query: function() {
    31443201                var dirtyCustomized = {};
    … …  
    34683525        }
    34693526
    3470         // Create a potential postMessage connection with the parent frame.
     3527        /*
     3528         * Create a postMessage connection with a parent frame,
     3529         * in case the Customizer frame was opened with the Customize loader.
     3530         *
     3531         * @see wp.customize.Loader
     3532         */
    34713533        parent = new api.Messenger({
    34723534            url: api.settings.url.parent,
    … …  
    34743536        });
    34753537
    3476         // If we receive a 'back' event, we're inside an iframe.
    3477         // Send any clicks to the 'Return' link to the parent page.
     3538        /*
     3539         * If we receive a 'back' event, we're inside an iframe.
     3540         * Send any clicks to the 'Return' link to the parent page.
     3541         */
    34783542        parent.bind( 'back', function() {
    34793543            closeBtn.on( 'click.customize-controls-close', function( event ) {
    … …  
    35003564        } );
    35013565
    3502         // When activated, let the loader handle redirecting the page.
    3503         // If no loader exists, redirect the page ourselves (if a url exists).
     3566        /*
     3567         * When activated, let the loader handle redirecting the page.
     3568         * If no loader exists, redirect the page ourselves (if a url exists).
     3569         */
    35043570        api.bind( 'activated', function() {
    35053571            if ( parent.targetWindow() )

  • trunk/src/wp-includes/class-wp-customize-setting.php

    r33488 r33911  
    2525
    2626    /**
     27     * Unique string identifier for the setting.
     28     *
    2729     * @access public
    2830     * @var string
    … …  
    7577    public $dirty = false;
    7678
     79    /**
     80     * @var array
     81     */
    7782    protected $id_data = array();
    7883
    … …  
    149154
    150155    /**
    151      * Handle previewing the setting.
     156     * Set up filters for the setting so that the preview request
     157     * will render the drafted changes.
    152158     *
    153159     * @since 3.4.0

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

    r33841 r33911  
    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 ) {
    … …  
    167169     */
    168170    api.Value = api.Class.extend({
     171        /**
     172         * @param {mixed}  initial The initial value.
     173         * @param {object} options
     174         */
    169175        initialize: function( initial, options ) {
    170176            this._value = initial; // @todo: potentially change this to a this.set() call.
    … …  
    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;
    … …  
    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 );
    … …  
    236257        },
    237258
     259        /**
     260         * Unbind a previously bound function.
     261         *
     262         * @param {...Function} A function, or multiple functions, to remove from the callback stack.
     263         */
    238264        unbind: function() {
    239265            this.callbacks.remove.apply( this.callbacks, arguments );
    … …  
    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
    … …  
    348380            this._value[ id ] = value;
    349381            value.parent = this;
     382
     383            // Propagate a 'change' event on an item up to the collection.
    350384            if ( value.extended( api.Value ) )
    351385                value.bind( this._change );
    … …  
    373407        },
    374408
     409        /**
     410         * Iterate over all items in the collection invoking the provided callback.
     411         *
     412         * @param  {Function} callback Function to invoke.
     413         * @param  {object}   context  Object context to invoke the function with. Optional.
     414         */
    375415        each: function( callback, context ) {
    376416            context = typeof context === 'undefined' ? this : context;
    … …  
    454494        },
    455495
     496        /**
     497         * A helper function to propagate a 'change' event from an item
     498         * to the collection itself.
     499         */
    456500        _change: function() {
    457501            this.parent.trigger( 'change', this );
    … …  
    459503    });
    460504
     505    // Create a global events bus on the Customizer.
    461506    $.extend( api.Values.prototype, api.Events );
    462507
    … …  
    571616
    572617    /**
    573      * Messenger for postMessage.
     618     * A communicator for sending data from one window to another over postMessage.
    574619     *
    575620     * @constuctor
    … …  
    650695        },
    651696
     697        /**
     698         * Receive data from the other window.
     699         *
     700         * @param  {jQuery.Event} event Event with embedded data.
     701         */
    652702        receive: function( event ) {
    653703            var message;
    … …  
    680730        },
    681731
     732        /**
     733         * Send data to the other window.
     734         *
     735         * @param  {string} id   The event name.
     736         * @param  {object} data Data.
     737         */
    682738        send: function( id, data ) {
    683739            var message;
    … …  
    699755    $.extend( api.Messenger.prototype, api.Events );
    700756
    701     // Core customize object.
     757    // The main API object is also a collection of all customizer settings.
    702758    api = $.extend( new api.Values(), api );
     759
     760    /**
     761     * Get all customize settings.
     762     *
     763     * @return {object}
     764     */
    703765    api.get = function() {
    704766        var result = {};

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

    r33709 r33911  
    116116            this.body.addClass('customize-loading');
    117117
    118             // Dirty state of Customizer in iframe
     118            /*
     119             * Track the dirtiness state (whether the drafted changes have been published)
     120             * of the Customizer in the iframe. This is used to decide whether to display
     121             * an AYS alert if the user tries to close the window before saving changes.
     122             */
    119123            this.saved = new api.Value( true );
    120124

  • trunk/src/wp-includes/js/customize-preview.js

    r33709 r33911  
    112112        });
    113113
     114        /*
     115         * Send a message to the parent customize frame with a list of which
     116         * containers and controls are active.
     117         */
    114118        api.preview.send( 'ready', {
    115119            activePanels: api.settings.activePanels,
Note: See TracChangeset for help on using the changeset viewer.