Changeset 33911

Timestamp:

09/05/2015 07:52:17 PM (9 years ago)

Author:

wonderboymusic

Message:

Add Customizer docs.

Props ericlewis.
See #33503.

Location:

trunk/src

Files:

• wp-admin/js/customize-controls.js (modified) (16 diffs)
• wp-includes/class-wp-customize-setting.php (modified) (3 diffs)
• wp-includes/js/customize-base.js (modified) (14 diffs)
• wp-includes/js/customize-loader.js (modified) (1 diff)
• wp-includes/js/customize-preview.js (modified) (1 diff)

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

@@ -4 +4 @@
 
     /**
+
+
+
+
+
+
+
      * @class
      * @augments wp.customize.Value
      * @augments wp.customize.Class
      *
-     * @param options
-     * - previewer - The Previewer instance to sync with.
-     * - transport - The transport to use for previewing. Supports 'refresh' and 'postMessage'.
+     * @param {object} id                The Setting ID.
+     * @param {object} value             The initial value of the setting.
+     * @param {object} options.previewer The Previewer instance to sync with.
+     * @param {object} options.transport The transport to use for previewing. Supports 'refresh' and 'postMessage'.
+     * @param {object} options.dirty
      */
     api.Setting = api.Value.extend({
@@ -20 +29 @@
             this._dirty = options.dirty || false;
 
+
             this.bind( this.preview );
         },
+
+
+
+
         preview: function() {
             switch ( this.transport ) {
@@ -271 +285 @@
 
         /**
-         * Handle changes to the active state.
-         *
-         * This does not change the active state, it merely handles the behavior
-         * for when it does change.
+         * Active state change handler.
+         *
+         * Shows the container if it is active, hides it if not.
          *
          * To override by subclass, update the container's UI to reflect the provided active state.
@@ -1348 +1361 @@
      * @augments wp.customize.Class
      *
-     * @param {string} id                            Unique identifier for the control instance.
-     * @param {object} options                       Options hash for the control instance.
+     * @param {string} id                            Unique identifier for the control instance.
+     * @param {object} options                       Options hash for the control instance.
      * @param {object} options.params
-     * @param {object} options.params.type           Type of control (e.g. text, radio, dropdown-pages, etc.)
-     * @param {string} options.params.content        The HTML content for the control.
-     * @param {string} options.params.priority       Order of priority to show the control within the section.
+     * @param {object} options.params.type           Type of control (e.g. text, radio, dropdown-pages, etc.)
+     * @param {string} options.params.content        The HTML content for the control.
+     * @param {string} options.params.priority       Order of priority to show the control within the section.
      * @param {string} options.params.active
-     * @param {string} options.params.section
+     * @param {string} options.params.section          The ID of the section the control belongs to.
+     * @param {string} options.params.settings.default The ID of the setting the control relates to.
+     * @param {string} options.params.settings.data
      * @param {string} options.params.label
      * @param {string} options.params.description
@@ -1421 +1436 @@
             api.utils.bubbleChildValueChanges( control, [ 'section', 'priority', 'active' ] );
 
-            // Associate this control with its settings when they are created
+            /*
+             * After all settings related to the control are available,
+             * make them available on the control and embed the control into the page.
+             */
             settings = $.map( control.params.settings, function( value ) {
                 return value;
@@ -1438 +1456 @@
             }) );
 
+
             control.deferred.embedded.done( function () {
                 control.ready();
@@ -2574 +2593 @@
 
     /**
+
+
+
      * @class
      * @augments wp.customize.Messenger
@@ -2582 +2604 @@
         sensitivity: 2000,
 
+
+
+
+
+
+
+
+
+
         initialize: function( params, options ) {
             var deferred = $.Deferred();
 
-            // This is the promise object.
+            /*
+             * Make the instance of the PreviewFrame the promise object
+             * so other objects can easily interact with it.
+             */
             deferred.promise( this );
 
@@ -2602 +2636 @@
         },
 
+
+
+
+
+
+
         run: function( deferred ) {
             var self   = this,
@@ -2805 +2845 @@
 
         /**
-         * Requires params:
-         *  - container  - a selector or jQuery element
-         *  - previewUrl - the URL of preview frame
+         * @param {array}  params.allowedUrls
+         * @param {string} params.container   A selector or jQuery element for the preview
+         *                                    frame to be placed.
+         * @param {string} params.form
+         * @param {string} params.previewUrl  The URL to preview.
+         * @param {string} params.signature
+         * @param {object} options
          */
         initialize: function( params, options ) {
@@ -2920 +2964 @@
         },
 
+
+
+
+
+
         query: function() {},
 
@@ -2929 +2978 @@
         },
 
+
+
+
         refresh: function() {
             var self = this;
@@ -3141 +3193 @@
             nonce: api.settings.nonce,
 
+
+
+
+
+
             query: function() {
                 var dirtyCustomized = {};
@@ -3468 +3525 @@
         }
 
-        // Create a potential postMessage connection with the parent frame.
+        /*
+         * Create a postMessage connection with a parent frame,
+         * in case the Customizer frame was opened with the Customize loader.
+         *
+         * @see wp.customize.Loader
+         */
         parent = new api.Messenger({
             url: api.settings.url.parent,
@@ -3474 +3536 @@
         });
 
-        // If we receive a 'back' event, we're inside an iframe.
-        // Send any clicks to the 'Return' link to the parent page.
+        /*
+         * If we receive a 'back' event, we're inside an iframe.
+         * Send any clicks to the 'Return' link to the parent page.
+         */
         parent.bind( 'back', function() {
             closeBtn.on( 'click.customize-controls-close', function( event ) {
@@ -3500 +3564 @@
         } );
 
-        // When activated, let the loader handle redirecting the page.
-        // If no loader exists, redirect the page ourselves (if a url exists).
+        /*
+         * When activated, let the loader handle redirecting the page.
+         * If no loader exists, redirect the page ourselves (if a url exists).
+         */
         api.bind( 'activated', function() {
             if ( parent.targetWindow() )

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

@@ -25 +25 @@
 
     /**
+
+
      * @access public
      * @var string
@@ -75 +77 @@
     public $dirty = false;
 
+
+
+
     protected $id_data = array();
 
@@ -149 +154 @@
 
     /**
-     * Handle previewing the setting.
+     * Set up filters for the setting so that the preview request
+     * will render the drafted changes.
      *
      * @since 3.4.0

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

@@ -79 +79 @@
          * If the class has a method called "instance",
          * the return value from the class' constructor will be a function that
-         * calls invoked, along with all the object properties of the class.
+         * calls the "instance" method.
+         *
+         * It is also an object that has properties and methods inside it.
          */
         if ( this.instance ) {
@@ -167 +169 @@
      */
     api.Value = api.Class.extend({
+
+
+
+
         initialize: function( initial, options ) {
             this._value = initial; // @todo: potentially change this to a this.set() call.
@@ -185 +191 @@
         },
 
+
+
+
+
+
         get: function() {
             return this._value;
         },
 
+
+
+
+
+
         set: function( to ) {
             var from = this._value;
@@ -231 +247 @@
         },
 
+
+
+
+
+
         bind: function() {
             this.callbacks.add.apply( this.callbacks, arguments );
@@ -236 +257 @@
         },
 
+
+
+
+
+
         unbind: function() {
             this.callbacks.remove.apply( this.callbacks, arguments );
@@ -284 +310 @@
      */
     api.Values = api.Class.extend({
+
+
+
+
+
+
         defaultConstructor: api.Value,
 
@@ -348 +380 @@
             this._value[ id ] = value;
             value.parent = this;
+
+
             if ( value.extended( api.Value ) )
                 value.bind( this._change );
@@ -373 +407 @@
         },
 
+
+
+
+
+
+
         each: function( callback, context ) {
             context = typeof context === 'undefined' ? this : context;
@@ -454 +494 @@
         },
 
+
+
+
+
         _change: function() {
             this.parent.trigger( 'change', this );
@@ -459 +503 @@
     });
 
+
     $.extend( api.Values.prototype, api.Events );
 
@@ -571 +616 @@
 
     /**
-     * Messenger for postMessage.
+     * r postMessage.
      *
      * @constuctor
@@ -650 +695 @@
         },
 
+
+
+
+
+
         receive: function( event ) {
             var message;
@@ -680 +730 @@
         },
 
+
+
+
+
+
+
         send: function( id, data ) {
             var message;
@@ -699 +755 @@
     $.extend( api.Messenger.prototype, api.Events );
 
-    // Core customize object.
+    // .
     api = $.extend( new api.Values(), api );
+
+
+
+
+
+
     api.get = function() {
         var result = {};

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

@@ -116 +116 @@
             this.body.addClass('customize-loading');
 
-            // Dirty state of Customizer in iframe
+            /*
+             * Track the dirtiness state (whether the drafted changes have been published)
+             * of the Customizer in the iframe. This is used to decide whether to display
+             * an AYS alert if the user tries to close the window before saving changes.
+             */
             this.saved = new api.Value( true );
 

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

@@ -112 +112 @@
         });
 
+
+
+
+
         api.preview.send( 'ready', {
             activePanels: api.settings.activePanels,