Changeset 30102

Timestamp:

10/29/2014 10:50:21 PM (10 years ago)

Author:

ocean90

Message:

Improve/introduce Customizer JavaScript models for Controls, Sections, and Panels.

• Introduce models for panels and sections.
• Introduce API to expand and focus a control, section or panel.
• Allow deep-linking to panels, sections, and controls inside of the Customizer.
• Clean up accordion.js, removing all Customizer-specific logic.
• Add initial unit tests for wp.customize.Class in customize-base.js.

​https://make.wordpress.org/core/2014/10/27/toward-a-complete-javascript-api-for-the-customizer/ provides an overview of how to use the JavaScript API.

props westonruter, celloexpressions, ryankienstra.
see #28032, #28579, #28580, #28650, #28709, #29758.
fixes #29529.

Location:

trunk

Files:

• src/wp-admin/customize.php (modified) (5 diffs)
• src/wp-admin/js/accordion.js (modified) (5 diffs)
• src/wp-admin/js/customize-controls.js (modified) (22 diffs)
• src/wp-admin/js/customize-widgets.js (modified) (25 diffs)
• src/wp-includes/class-wp-customize-control.php (modified) (5 diffs)
• src/wp-includes/class-wp-customize-manager.php (modified) (4 diffs)
• src/wp-includes/class-wp-customize-panel.php (modified) (5 diffs)
• src/wp-includes/class-wp-customize-section.php (modified) (7 diffs)
• src/wp-includes/js/customize-base.js (modified) (1 diff)
• src/wp-includes/js/customize-preview.js (modified) (1 diff)
• tests/qunit/index.html (modified) (4 diffs)
• tests/qunit/wp-admin/js/customize-base.js (added)

trunk/src/wp-admin/customize.php

@@ -54 +54 @@
 wp_enqueue_style( 'customize-controls' );
 
-wp_enqueue_script( 'accordion' );
-
 /**
  * Enqueue Customizer control scripts.
@@ -131 +129 @@
 
         <div id="widgets-right"><!-- For Widget Customizer, many widgets try to look for instances under div#widgets-right, so we have to add that ID to a container div in the Customizer for compat -->
-        <div class="wp-full-overlay-sidebar-content accordion-container" tabindex="-1">
+        <div class="wp-full-overlay-sidebar-content" tabindex="-1">
             <div id="customize-info" class="accordion-section <?php if ( $cannot_expand ) echo ' cannot-expand'; ?>">
                 <div class="accordion-section-title" aria-label="<?php esc_attr_e( 'Customizer Options' ); ?>" tabindex="0">
@@ -161 +159 @@
             </div>
 
-            <div id="customize-theme-controls"><ul>
-                <?php
-                foreach ( $wp_customize->containers() as $container ) {
-                    $container->maybe_render();
-                }
-                ?>
-            </ul></div>
+            <div id="customize-theme-controls">
+                <ul><?php // Panels and sections are managed here via JavaScript ?></ul>
+            </div>
         </div>
         </div>
@@ -253 +247 @@
         'settings' => array(),
         'controls' => array(),
+        'panels'   => array(),
+        'sections' => array(),
         'nonce'    => array(
             'save'    => wp_create_nonce( 'save-customize_' . $wp_customize->get_stylesheet() ),
             'preview' => wp_create_nonce( 'preview-customize_' . $wp_customize->get_stylesheet() )
         ),
+        'autofocus' => array(),
     );
 
@@ -267 +264 @@
     }
 
-    // Prepare Customize Control objects to pass to Javascript.
+    // Prepare Customize Control objects to pass to JavaScript.
     foreach ( $wp_customize->controls() as $id => $control ) {
-        $control->to_json();
-        $settings['controls'][ $id ] = $control->json;
+        $settings['controls'][ $id ] = $control->json();
+    }
+
+    // Prepare Customize Section objects to pass to JavaScript.
+    foreach ( $wp_customize->sections() as $id => $section ) {
+        $settings['sections'][ $id ] = $section->json();
+    }
+
+    // Prepare Customize Panel objects to pass to JavaScript.
+    foreach ( $wp_customize->panels() as $id => $panel ) {
+        $settings['panels'][ $id ] = $panel->json();
+        foreach ( $panel->sections as $section_id => $section ) {
+            $settings['sections'][ $section_id ] = $section->json();
+        }
+    }
+
+    // Pass to frontend the Customizer construct being deeplinked
+    if ( isset( $_GET['autofocus'] ) && is_array( $_GET['autofocus'] ) ) {
+        $autofocus = wp_unslash( $_GET['autofocus'] );
+        foreach ( $autofocus as $type => $id ) {
+            if ( isset( $settings[ $type . 's' ][ $id ] ) ) {
+                $settings['autofocus'][ $type ] = $id;
+            }
+        }
     }
 

trunk/src/wp-admin/js/accordion.js

@@ -26 +26 @@
  * Note that any appropriate tags may be used, as long as the above classes are present.
  *
- * In addition to the standard accordion behavior, this file includes JS for the
- * Customizer's "Panel" functionality.
- *
  * @since 3.6.0.
  */
@@ -47 +44 @@
         });
 
-        // Go back to the top-level Customizer accordion.
-        $( '#customize-header-actions' ).on( 'click keydown', '.control-panel-back', function( e ) {
-            if ( e.type === 'keydown' && 13 !== e.which ) { // "return" key
-                return;
-            }
-
-            e.preventDefault(); // Keep this AFTER the key filter above
-
-            panelSwitch( $( '.current-panel' ) );
-        });
     });
-
-    var sectionContent = $( '.accordion-section-content' );
 
     /**
@@ -70 +55 @@
         var section = el.closest( '.accordion-section' ),
             siblings = section.closest( '.accordion-container' ).find( '.open' ),
-            content = section.find( sectionContent );
+            content = section.find( '.accordion-section-content' );
 
         // This section has no content and cannot be expanded.
         if ( section.hasClass( 'cannot-expand' ) ) {
-            return;
-        }
-
-        // Slide into a sub-panel instead of accordioning (Customizer-specific).
-        if ( section.hasClass( 'control-panel' ) ) {
-            panelSwitch( section );
             return;
         }
@@ -88 +67 @@
         } else {
             siblings.removeClass( 'open' );
-            siblings.find( sectionContent ).show().slideUp( 150 );
+            siblings.find( '.accordion-section-content' ).show().slideUp( 150 );
             content.toggle( false ).slideToggle( 150 );
             section.toggleClass( 'open' );
@@ -94 +73 @@
     }
 
-    /**
-     * Slide into an accordion sub-panel.
-     *
-     * For the Customizer-specific panel functionality
-     *
-     * @param {Object} panel Title element or back button of the accordion panel to toggle.
-     * @since 4.0.0
-     */
-    function panelSwitch( panel ) {
-        var position, scroll,
-            section = panel.closest( '.accordion-section' ),
-            overlay = section.closest( '.wp-full-overlay' ),
-            container = section.closest( '.accordion-container' ),
-            siblings = container.find( '.open' ),
-            topPanel = overlay.find( '#customize-theme-controls > ul > .accordion-section > .accordion-section-title' ).add( '#customize-info > .accordion-section-title' ),
-            backBtn = overlay.find( '.control-panel-back' ),
-            panelTitle = section.find( '.accordion-section-title' ).first(),
-            content = section.find( '.control-panel-content' );
-
-        if ( section.hasClass( 'current-panel' ) ) {
-            section.toggleClass( 'current-panel' );
-            overlay.toggleClass( 'in-sub-panel' );
-            content.delay( 180 ).hide( 0, function() {
-                content.css( 'margin-top', 'inherit' ); // Reset
-            } );
-            topPanel.attr( 'tabindex', '0' );
-            backBtn.attr( 'tabindex', '-1' );
-            panelTitle.focus();
-            container.scrollTop( 0 );
-        } else {
-            // Close all open sections in any accordion level.
-            siblings.removeClass( 'open' );
-            siblings.find( sectionContent ).show().slideUp( 0 );
-            content.show( 0, function() {
-                position = content.offset().top;
-                scroll = container.scrollTop();
-                content.css( 'margin-top', ( 45 - position - scroll ) );
-                section.toggleClass( 'current-panel' );
-                overlay.toggleClass( 'in-sub-panel' );
-                container.scrollTop( 0 );
-            } );
-            topPanel.attr( 'tabindex', '-1' );
-            backBtn.attr( 'tabindex', '0' );
-            backBtn.focus();
-        }
-    }
-
 })(jQuery);

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

@@ -1 +1 @@
 /* globals _wpCustomizeHeader, _wpMediaViewsL10n */
 (function( exports, $ ){
-    var api = wp.customize;
+    var bubbleChildValueChanges, Container, focus, isKeydownButNotEnterEvent, areElementListsEqual, api = wp.customize;
+
+    // @todo Move private helper functions to wp.customize.utils so they can be unit tested
 
     /**
@@ -32 +34 @@
 
     /**
+     * Watch all changes to Value properties, and bubble changes to parent Values instance
+     *
+     * @param {wp.customize.Class} instance
+     * @param {Array} properties  The names of the Value instances to watch.
+     */
+    bubbleChildValueChanges = function ( instance, properties ) {
+        $.each( properties, function ( i, key ) {
+            instance[ key ].bind( function ( to, from ) {
+                if ( instance.parent && to !== from ) {
+                    instance.parent.trigger( 'change', instance );
+                }
+            } );
+        } );
+    };
+
+    /**
+     * Expand a panel, section, or control and focus on the first focusable element.
+     *
+     * @param {Object} [params]
+     */
+    focus = function ( params ) {
+        var construct, completeCallback, focus;
+        construct = this;
+        params = params || {};
+        focus = function () {
+            construct.container.find( ':focusable:first' ).focus();
+            construct.container[0].scrollIntoView( true );
+        };
+        if ( params.completeCallback ) {
+            completeCallback = params.completeCallback;
+            params.completeCallback = function () {
+                focus();
+                completeCallback();
+            };
+        } else {
+            params.completeCallback = focus;
+        }
+        if ( construct.expand ) {
+            construct.expand( params );
+        } else {
+            params.completeCallback();
+        }
+    };
+
+    /**
+     * Return whether the supplied Event object is for a keydown event but not the Enter key.
+     *
+     * @param {jQuery.Event} event
+     * @returns {boolean}
+     */
+    isKeydownButNotEnterEvent = function ( event ) {
+        return ( 'keydown' === event.type && 13 !== event.which );
+    };
+
+    /**
+     * Return whether the two lists of elements are the same and are in the same order.
+     *
+     * @param {Array|jQuery} listA
+     * @param {Array|jQuery} listB
+     * @returns {boolean}
+     */
+    areElementListsEqual = function ( listA, listB ) {
+        var equal = (
+            listA.length === listB.length && // if lists are different lengths, then naturally they are not equal
+            -1 === _.map( // are there any false values in the list returned by map?
+                _.zip( listA, listB ), // pair up each element between the two lists
+                function ( pair ) {
+                    return $( pair[0] ).is( pair[1] ); // compare to see if each pair are equal
+                }
+            ).indexOf( false ) // check for presence of false in map's return value
+        );
+        return equal;
+    };
+
+    /**
+     * Base class for Panel and Section
+     *
+     * @constructor
+     * @augments wp.customize.Class
+     */
+    Container = api.Class.extend({
+        defaultActiveArguments: { duration: 'fast' },
+        defaultExpandedArguments: { duration: 'fast' },
+
+        initialize: function ( id, options ) {
+            var container = this;
+            container.id = id;
+            container.params = {};
+            $.extend( container, options || {} );
+            container.container = $( container.params.content );
+
+            container.deferred = {
+                ready: new $.Deferred()
+            };
+            container.priority = new api.Value();
+            container.active = new api.Value();
+            container.activeArgumentsQueue = [];
+            container.expanded = new api.Value();
+            container.expandedArgumentsQueue = [];
+
+            container.active.bind( function ( active ) {
+                var args = container.activeArgumentsQueue.shift();
+                args = $.extend( {}, container.defaultActiveArguments, args );
+                active = ( active && container.isContextuallyActive() );
+                container.onChangeActive( active, args );
+                // @todo trigger 'activated' and 'deactivated' events based on the expanded param?
+            });
+            container.expanded.bind( function ( expanded ) {
+                var args = container.expandedArgumentsQueue.shift();
+                args = $.extend( {}, container.defaultExpandedArguments, args );
+                container.onChangeExpanded( expanded, args );
+                // @todo trigger 'expanded' and 'collapsed' events based on the expanded param?
+            });
+
+            container.attachEvents();
+
+            bubbleChildValueChanges( container, [ 'priority', 'active' ] );
+
+            container.priority.set( isNaN( container.params.priority ) ? 100 : container.params.priority );
+            container.active.set( container.params.active );
+            container.expanded.set( false ); // @todo True if deeplinking?
+        },
+
+        /**
+         * @abstract
+         */
+        ready: function() {},
+
+        /**
+         * Get the child models associated with this parent, sorting them by their priority Value.
+         *
+         * @param {String} parentType
+         * @param {String} childType
+         * @returns {Array}
+         */
+        _children: function ( parentType, childType ) {
+            var parent = this,
+                children = [];
+            api[ childType ].each( function ( child ) {
+                if ( child[ parentType ].get() === parent.id ) {
+                    children.push( child );
+                }
+            } );
+            children.sort( function ( a, b ) {
+                return a.priority() - b.priority();
+            } );
+            return children;
+        },
+
+        /**
+         * To override by subclass, to return whether the container has active children.
+         * @abstract
+         */
+        isContextuallyActive: function () {
+            throw new Error( 'Must override with subclass.' );
+        },
+
+        /**
+         * Handle changes to the active state.
+         * This does not change the active state, it merely handles the behavior
+         * for when it does change.
+         *
+         * To override by subclass, update the container's UI to reflect the provided active state.
+         *
+         * @param {Boolean} active
+         * @param {Object} args  merged on top of this.defaultActiveArguments
+         */
+        onChangeActive: function ( active, args ) {
+            var duration = ( 'resolved' === api.previewer.deferred.active.state() ? args.duration : 0 );
+            if ( active ) {
+                this.container.stop( true, true ).slideDown( duration, args.completeCallback );
+            } else {
+                this.container.stop( true, true ).slideUp( duration, args.completeCallback );
+            }
+        },
+
+        /**
+         * @params {Boolean} active
+         * @param {Object} [params]
+         * @returns {Boolean} false if state already applied
+         */
+        _toggleActive: function ( active, params ) {
+            var self = this;
+            params = params || {};
+            if ( ( active && this.active.get() ) || ( ! active && ! this.active.get() ) ) {
+                params.unchanged = true;
+                self.onChangeActive( self.active.get(), params );
+                return false;
+            } else {
+                params.unchanged = false;
+                this.activeArgumentsQueue.push( params );
+                this.active.set( active );
+                return true;
+            }
+        },
+
+        /**
+         * @param {Object} [params]
+         * @returns {Boolean} false if already active
+         */
+        activate: function ( params ) {
+            return this._toggleActive( true, params );
+        },
+
+        /**
+         * @param {Object} [params]
+         * @returns {Boolean} false if already inactive
+         */
+        deactivate: function ( params ) {
+            return this._toggleActive( false, params );
+        },
+
+        /**
+         * To override by subclass, update the container's UI to reflect the provided active state.
+         * @abstract
+         */
+        onChangeExpanded: function () {
+            throw new Error( 'Must override with subclass.' );
+        },
+
+        /**
+         * @param {Boolean} expanded
+         * @param {Object} [params]
+         * @returns {Boolean} false if state already applied
+         */
+        _toggleExpanded: function ( expanded, params ) {
+            var self = this;
+            params = params || {};
+            if ( ( expanded && this.expanded.get() ) || ( ! expanded && ! this.expanded.get() ) ) {
+                params.unchanged = true;
+                self.onChangeExpanded( self.expanded.get(), params );
+                return false;
+            } else {
+                params.unchanged = false;
+                this.expandedArgumentsQueue.push( params );
+                this.expanded.set( expanded );
+                return true;
+            }
+        },
+
+        /**
+         * @param {Object} [params]
+         * @returns {Boolean} false if already expanded
+         */
+        expand: function ( params ) {
+            return this._toggleExpanded( true, params );
+        },
+
+        /**
+         * @param {Object} [params]
+         * @returns {Boolean} false if already collapsed
+         */
+        collapse: function ( params ) {
+            return this._toggleExpanded( false, params );
+        },
+
+        /**
+         * Bring the container into view and then expand this and bring it into view
+         * @param {Object} [params]
+         */
+        focus: focus
+    });
+
+    /**
+     * @constructor
+     * @augments wp.customize.Class
+     */
+    api.Section = Container.extend({
+
+        /**
+         * @param {String} id
+         * @param {Array} options
+         */
+        initialize: function ( id, options ) {
+            var section = this;
+            Container.prototype.initialize.call( section, id, options );
+
+            section.id = id;
+            section.panel = new api.Value();
+            section.panel.bind( function ( id ) {
+                $( section.container ).toggleClass( 'control-subsection', !! id );
+            });
+            section.panel.set( section.params.panel || '' );
+            bubbleChildValueChanges( section, [ 'panel' ] );
+
+            section.embed();
+            section.deferred.ready.done( function () {
+                section.ready();
+            });
+        },
+
+        /**
+         * Embed the container in the DOM when any parent panel is ready.
+         */
+        embed: function () {
+            var section = this, inject;
+
+            // Watch for changes to the panel state
+            inject = function ( panelId ) {
+                var parentContainer;
+                if ( panelId ) {
+                    // The panel has been supplied, so wait until the panel object is registered
+                    api.panel( panelId, function ( panel ) {
+                        // The panel has been registered, wait for it to become ready/initialized
+                        panel.deferred.ready.done( function () {
+                            parentContainer = panel.container.find( 'ul:first' );
+                            if ( ! section.container.parent().is( parentContainer ) ) {
+                                parentContainer.append( section.container );
+                            }
+                            section.deferred.ready.resolve(); // @todo Better to use `embedded` instead of `ready`
+                        });
+                    } );
+                } else {
+                    // There is no panel, so embed the section in the root of the customizer
+                    parentContainer = $( '#customize-theme-controls' ).children( 'ul' ); // @todo This should be defined elsewhere, and to be configurable
+                    if ( ! section.container.parent().is( parentContainer ) ) {
+                        parentContainer.append( section.container );
+                    }
+                    section.deferred.ready.resolve();
+                }
+            };
+            section.panel.bind( inject );
+            inject( section.panel.get() ); // Since a section may never get a panel, assume that it won't ever get one
+        },
+
+        /**
+         * Add behaviors for the accordion section
+         */
+        attachEvents: function () {
+            var section = this;
+
+            // Expand/Collapse accordion sections on click.
+            section.container.find( '.accordion-section-title' ).on( 'click keydown', function( event ) {
+                if ( isKeydownButNotEnterEvent( event ) ) {
+                    return;
+                }
+                event.preventDefault(); // Keep this AFTER the key filter above
+
+                if ( section.expanded() ) {
+                    section.collapse();
+                } else {
+                    section.expand();
+                }
+            });
+        },
+
+        /**
+         * Return whether this section has any active controls.
+         *
+         * @returns {boolean}
+         */
+        isContextuallyActive: function () {
+            var section = this,
+                controls = section.controls(),
+                activeCount = 0;
+            _( controls ).each( function ( control ) {
+                if ( control.active() ) {
+                    activeCount += 1;
+                }
+            } );
+            return ( activeCount !== 0 );
+        },
+
+        /**
+         * Get the controls that are associated with this section, sorted by their priority Value.
+         *
+         * @returns {Array}
+         */
+        controls: function () {
+            return this._children( 'section', 'control' );
+        },
+
+        /**
+         * Update UI to reflect expanded state
+         *
+         * @param {Boolean} expanded
+         * @param {Object} args
+         */
+        onChangeExpanded: function ( expanded, args ) {
+            var section = this,
+                content = section.container.find( '.accordion-section-content' ),
+                expand;
+
+            if ( expanded ) {
+
+                if ( args.unchanged ) {
+                    expand = args.completeCallback;
+                } else {
+                    expand = function () {
+                        content.stop().slideDown( args.duration, args.completeCallback );
+                        section.container.addClass( 'open' );
+                    };
+                }
+
+                if ( ! args.allowMultiple ) {
+                    api.section.each( function ( otherSection ) {
+                        if ( otherSection !== section ) {
+                            otherSection.collapse( { duration: args.duration } );
+                        }
+                    });
+                }
+
+                if ( section.panel() ) {
+                    api.panel( section.panel() ).expand({
+                        duration: args.duration,
+                        completeCallback: expand
+                    });
+                } else {
+                    expand();
+                }
+
+            } else {
+                section.container.removeClass( 'open' );
+                content.slideUp( args.duration, args.completeCallback );
+            }
+        }
+    });
+
+    /**
+     * @constructor
+     * @augments wp.customize.Class
+     */
+    api.Panel = Container.extend({
+        initialize: function ( id, options ) {
+            var panel = this;
+            Container.prototype.initialize.call( panel, id, options );
+            panel.embed();
+            panel.deferred.ready.done( function () {
+                panel.ready();
+            });
+        },
+
+        /**
+         * Embed the container in the DOM when any parent panel is ready.
+         */
+        embed: function () {
+            var panel = this,
+                parentContainer = $( '#customize-theme-controls > ul' ); // @todo This should be defined elsewhere, and to be configurable
+
+            if ( ! panel.container.parent().is( parentContainer ) ) {
+                parentContainer.append( panel.container );
+            }
+            panel.deferred.ready.resolve();
+        },
+
+        /**
+         *
+         */
+        attachEvents: function () {
+            var meta, panel = this;
+
+            // Expand/Collapse accordion sections on click.
+            panel.container.find( '.accordion-section-title' ).on( 'click keydown', function( event ) {
+                if ( isKeydownButNotEnterEvent( event ) ) {
+                    return;
+                }
+                event.preventDefault(); // Keep this AFTER the key filter above
+
+                if ( ! panel.expanded() ) {
+                    panel.expand();
+                }
+            });
+
+            meta = panel.container.find( '.panel-meta:first' );
+
+            meta.find( '> .accordion-section-title' ).on( 'click keydown', function( event ) {
+                if ( isKeydownButNotEnterEvent( event ) ) {
+                    return;
+                }
+                event.preventDefault(); // Keep this AFTER the key filter above
+
+                if ( meta.hasClass( 'cannot-expand' ) ) {
+                    return;
+                }
+
+                var content = meta.find( '.accordion-section-content:first' );
+                if ( meta.hasClass( 'open' ) ) {
+                    meta.toggleClass( 'open' );
+                    content.slideUp( panel.defaultExpandedArguments.duration );
+                } else {
+                    content.slideDown( panel.defaultExpandedArguments.duration );
+                    meta.toggleClass( 'open' );
+                }
+            });
+
+        },
+
+        /**
+         * Get the sections that are associated with this panel, sorted by their priority Value.
+         *
+         * @returns {Array}
+         */
+        sections: function () {
+            return this._children( 'panel', 'section' );
+        },
+
+        /**
+         * Return whether this panel has any active sections.
+         *
+         * @returns {boolean}
+         */
+        isContextuallyActive: function () {
+            var panel = this,
+                sections = panel.sections(),
+                activeCount = 0;
+            _( sections ).each( function ( section ) {
+                if ( section.active() && section.isContextuallyActive() ) {
+                    activeCount += 1;
+                }
+            } );
+            return ( activeCount !== 0 );
+        },
+
+        /**
+         * Update UI to reflect expanded state
+         *
+         * @param {Boolean} expanded
+         * @param {Object} args  merged with this.defaultExpandedArguments
+         */
+        onChangeExpanded: function ( expanded, args ) {
+
+            // Immediately call the complete callback if there were no changes
+            if ( args.unchanged ) {
+                if ( args.completeCallback ) {
+                    args.completeCallback();
+                }
+                return;
+            }
+
+            // Note: there is a second argument 'args' passed
+            var position, scroll,
+                panel = this,
+                section = panel.container.closest( '.accordion-section' ),
+                overlay = section.closest( '.wp-full-overlay' ),
+                container = section.closest( '.accordion-container' ),
+                siblings = container.find( '.open' ),
+                topPanel = overlay.find( '#customize-theme-controls > ul > .accordion-section > .accordion-section-title' ).add( '#customize-info > .accordion-section-title' ),
+                backBtn = overlay.find( '.control-panel-back' ),
+                panelTitle = section.find( '.accordion-section-title' ).first(),
+                content = section.find( '.control-panel-content' );
+
+            if ( expanded ) {
+
+                // Collapse any sibling sections/panels
+                api.section.each( function ( section ) {
+                    if ( ! section.panel() ) {
+                        section.collapse( { duration: 0 } );
+                    }
+                });
+                api.panel.each( function ( otherPanel ) {
+                    if ( panel !== otherPanel ) {
+                        otherPanel.collapse( { duration: 0 } );
+                    }
+                });
+
+                content.show( 0, function() {
+                    position = content.offset().top;
+                    scroll = container.scrollTop();
+                    content.css( 'margin-top', ( 45 - position - scroll ) );
+                    section.addClass( 'current-panel' );
+                    overlay.addClass( 'in-sub-panel' );
+                    container.scrollTop( 0 );
+                    if ( args.completeCallback ) {
+                        args.completeCallback();
+                    }
+                } );
+                topPanel.attr( 'tabindex', '-1' );
+                backBtn.attr( 'tabindex', '0' );
+                backBtn.focus();
+            } else {
+                siblings.removeClass( 'open' );
+                section.removeClass( 'current-panel' );
+                overlay.removeClass( 'in-sub-panel' );
+                content.delay( 180 ).hide( 0, function() {
+                    content.css( 'margin-top', 'inherit' ); // Reset
+                    if ( args.completeCallback ) {
+                        args.completeCallback();
+                    }
+                } );
+                topPanel.attr( 'tabindex', '0' );
+                backBtn.attr( 'tabindex', '-1' );
+                panelTitle.focus();
+                container.scrollTop( 0 );
+            }
+        }
+    });
+
+    /**
      * @constructor
      * @augments wp.customize.Class
      */
     api.Control = api.Class.extend({
+        defaultActiveArguments: { duration: 'fast' },
+
         initialize: function( id, options ) {
             var control = this,
                 nodes, radios, settings;
 
-            this.params = {};
-            $.extend( this, options || {} );
-
-            this.id = id;
-            this.selector = '#customize-control-' + id.replace( /\]/g, '' ).replace( /\[/g, '-' );
-            this.container = $( this.selector );
-            this.active = new api.Value( this.params.active );
-
-            settings = $.map( this.params.settings, function( value ) {
-                return value;
-            });
-
-            api.apply( api, settings.concat( function() {
-                var key;
-
-                control.settings = {};
-                for ( key in control.params.settings ) {
-                    control.settings[ key ] = api( control.params.settings[ key ] );
-                }
-
-                control.setting = control.settings['default'] || null;
-                control.renderContent( function() {
-                    // Don't call ready() until the content has rendered.
-                    control.ready();
-                } );
-            }) );
+            control.params = {};
+            $.extend( control, options || {} );
+
+            control.id = id;
+            control.selector = '#customize-control-' + id.replace( /\]/g, '' ).replace( /\[/g, '-' );
+            control.templateSelector = 'customize-control-' + control.params.type + '-content';
+            control.container = control.params.content ? $( control.params.content ) : $( control.selector );
+
+            control.deferred = {
+                ready: new $.Deferred()
+            };
+            control.section = new api.Value();
+            control.priority = new api.Value();
+            control.active = new api.Value();
+            control.activeArgumentsQueue = [];
 
             control.elements = [];
 
-            nodes  = this.container.find('[data-customize-setting-link]');
+            nodes  = control.container.find('[data-customize-setting-link]');
             radios = {};
 
             nodes.each( function() {
-                var node = $(this),
+                var node = $( this ),
                     name;
 
-                if ( node.is(':radio') ) {
-                    name = node.prop('name');
-                    if ( radios[ name ] )
+                if ( node.is( ':radio' ) ) {
+                    name = node.prop( 'name' );
+                    if ( radios[ name ] ) {
                         return;
+                    }
 
                     radios[ name ] = true;
@@ -85 +667 @@
                 }
 
-                api( node.data('customizeSettingLink'), function( setting ) {
+                api( node.data( 'customizeSettingLink' ), function( setting ) {
                     var element = new api.Element( node );
                     control.elements.push( element );
@@ -94 +676 @@
 
             control.active.bind( function ( active ) {
-                control.toggle( active );
+                var args = control.activeArgumentsQueue.shift();
+                args = $.extend( {}, control.defaultActiveArguments, args );
+                control.onChangeActive( active, args );
             } );
-            control.toggle( control.active() );
+
+            control.section.set( control.params.section );
+            control.priority.set( isNaN( control.params.priority ) ? 10 : control.params.priority );
+            control.active.set( control.params.active );
+
+            bubbleChildValueChanges( control, [ 'section', 'priority', 'active' ] );
+
+            // Associate this control with its settings when they are created
+            settings = $.map( control.params.settings, function( value ) {
+                return value;
+            });
+            api.apply( api, settings.concat( function () {
+                var key;
+
+                control.settings = {};
+                for ( key in control.params.settings ) {
+                    control.settings[ key ] = api( control.params.settings[ key ] );
+                }
+
+                control.setting = control.settings['default'] || null;
+
+                control.embed();
+            }) );
+
+            control.deferred.ready.done( function () {
+                control.ready();
+            });
+        },
+
+        /**
+         *
+         */
+        embed: function () {
+            var control = this,
+                inject;
+
+            // Watch for changes to the section state
+            inject = function ( sectionId ) {
+                var parentContainer;
+                if ( ! sectionId ) { // @todo allow a control to be embeded without a section, for instance a control embedded in the frontend
+                    return;
+                }
+                // Wait for the section to be registered
+                api.section( sectionId, function ( section ) {
+                    // Wait for the section to be ready/initialized
+                    section.deferred.ready.done( function () {
+                        parentContainer = section.container.find( 'ul:first' );
+                        if ( ! control.container.parent().is( parentContainer ) ) {
+                            parentContainer.append( control.container );
+                            control.renderContent();
+                        }
+                        control.deferred.ready.resolve(); // @todo Better to use `embedded` instead of `ready`
+                    });
+                });
+            };
+            control.section.bind( inject );
+            inject( control.section.get() );
         },
 
@@ -105 +745 @@
 
         /**
-         * Callback for change to the control's active state.
+         * Normal controls do not expand, so just expand its parent
          *
-         * Override function for custom behavior for the control being active/inactive.
+         * @param {Object} [params]
+         */
+        expand: function ( params ) {
+            api.section( this.section() ).expand( params );
+        },
+
+        /**
+         * Bring the containing section and panel into view and then this control into view, focusing on the first input
+         */
+        focus: focus,
+
+        /**
+         * Update UI in response to a change in the control's active state.
+         * This does not change the active state, it merely handles the behavior
+         * for when it does change.
          *
          * @param {Boolean} active
+         * @param {Object} args  merged on top of this.defaultActiveArguments
+         */
+        onChangeActive: function ( active, args ) {
+            if ( active ) {
+                this.container.slideDown( args.duration, args.completeCallback );
+            } else {
+                this.container.slideUp( args.duration, args.completeCallback );
+            }
+        },
+
+        /**
+         * @deprecated alias of onChangeActive
          */
         toggle: function ( active ) {
-            if ( active ) {
-                this.container.slideDown();
-            } else {
-                this.container.slideUp();
-            }
-        },
+            return this.onChangeActive( active, this.defaultActiveArguments );
+        },
+
+        /**
+         * Shorthand way to enable the active state.
+         *
+         * @param {Object} [params]
+         * @returns {Boolean} false if already active
+         */
+        activate: Container.prototype.activate,
+
+        /**
+         * Shorthand way to disable the active state.
+         *
+         * @param {Object} [params]
+         * @returns {Boolean} false if already inactive
+         */
+        deactivate: Container.prototype.deactivate,
 
         dropdownInit: function() {
@@ -133 +811 @@
             // Support the .dropdown class to open/close complex elements
             this.container.on( 'click keydown', '.dropdown', function( event ) {
-                if ( event.type === 'keydown' &&  13 !== event.which ) // enter
+                if ( isKeydownButNotEnterEvent( event ) ) {
                     return;
+                }
 
                 event.preventDefault();
@@ -158 +837 @@
          * Render the control from its JS template, if it exists.
          *
-         * The control's container must alreasy exist in the DOM.
-         */
-        renderContent: function( callback ) {
+         * The control's container must already exist in the DOM.
+         */
+        renderContent: function () {
             var template,
-                selector = 'customize-control-' + this.params.type + '-content';
-
-            callback = callback || function(){};
-            if ( 0 !== $( '#tmpl-' + selector ).length ) {
-                template = wp.template( selector );
-                if ( template && this.container ) {
-                    this.container.append( template( this.params ) );
-                }
-            }
-            callback();
+                control = this;
+
+            if ( 0 !== $( '#tmpl-' + control.templateSelector ).length ) {
+                template = wp.template( control.templateSelector );
+                if ( template && control.container ) {
+                    control.container.append( template( control.params ) );
+                }
+            }
         }
     });
@@ -235 +912 @@
             this.remover = this.container.find('.remove');
             this.remover.on( 'click keydown', function( event ) {
-                if ( event.type === 'keydown' &&  13 !== event.which ) // enter
+                if ( isKeydownButNotEnterEvent( event ) ) {
                     return;
+                }
 
                 control.setting.set( control.params.removed );
@@ -307 +985 @@
             // Bind tab switch events
             this.library.children('ul').on( 'click keydown', 'li', function( event ) {
-                if ( event.type === 'keydown' &&  13 !== event.which ) // enter
+                if ( isKeydownButNotEnterEvent( event ) ) {
                     return;
+                }
 
                 var id  = $(this).data('customizeTab'),
@@ -325 +1004 @@
             // Bind events to switch image urls.
             this.library.on( 'click keydown', 'a', function( event ) {
-                if ( event.type === 'keydown' && 13 !== event.which ) // enter
+                if ( isKeydownButNotEnterEvent( event ) ) {
                     return;
+                }
 
                 var value = $(this).data('customizeImageValue');
@@ -598 +1278 @@
     // Create the collection of Control objects.
     api.control = new api.Values({ defaultConstructor: api.Control });
+    api.section = new api.Values({ defaultConstructor: api.Section });
+    api.panel = new api.Values({ defaultConstructor: api.Panel });
 
     /**
@@ -633 +1315 @@
                 ready  = false;
 
-            if ( this._ready )
+            if ( this._ready ) {
                 this.unbind( 'ready', this._ready );
+            }
 
             this._ready = function() {
                 ready = true;
 
-                if ( loaded )
+                if ( loaded ) {
                     deferred.resolveWith( self );
+                }
             };
 
@@ -646 +1330 @@
 
             this.bind( 'ready', function ( data ) {
-                if ( ! data || ! data.activeControls ) {
+                if ( ! data ) {
                     return;
                 }
 
-                $.each( data.activeControls, function ( id, active ) {
-                    var control = api.control( id );
-                    if ( control ) {
-                        control.active( active );
+                var constructs = {
+                    panel: data.activePanels,
+                    section: data.activeSections,
+                    control: data.activeControls
+                };
+
+                $.each( constructs, function ( type, activeConstructs ) {
+                    if ( activeConstructs ) {
+                        $.each( activeConstructs, function ( id, active ) {
+                            var construct = api[ type ]( id );
+                            if ( construct ) {
+                                construct.active( active );
+                            }
+                        } );
                     }
                 } );
+
             } );
 
@@ -677 +1372 @@
                 // Check if the location response header differs from the current URL.
                 // If so, the request was redirected; try loading the requested page.
-                if ( location && location != self.previewUrl() ) {
+                if ( location && location !== self.previewUrl() ) {
                     deferred.rejectWith( self, [ 'redirect', location ] );
                     return;
@@ -804 +1499 @@
 
             $.extend( this, options || {} );
+            this.deferred = {
+                active: $.Deferred()
+            };
 
             /*
@@ -935 +1633 @@
                     self.channel( this.channel() );
 
+                    self.deferred.active.resolve();
                     self.send( 'active' );
                 });
@@ -1002 +1701 @@
         header: api.HeaderControl
     };
+    api.panelConstructor = {};
+    api.sectionConstructor = {};
 
     $( function() {
@@ -1029 +1730 @@
             if ( isEnter && ( $el.is( 'input:not([type=button])' ) || $el.is( 'select' ) ) ) {
                 e.preventDefault();
+            }
+        });
+
+        // Expand/Collapse the main customizer customize info
+        $( '#customize-info' ).find( '> .accordion-section-title' ).on( 'click keydown', function( event ) {
+            if ( isKeydownButNotEnterEvent( event ) ) {
+                return;
+            }
+            event.preventDefault(); // Keep this AFTER the key filter above
+
+            var section = $( this ).parent(),
+                content = section.find( '.accordion-section-content:first' );
+
+            if ( section.hasClass( 'cannot-expand' ) ) {
+                return;
+            }
+
+            if ( section.hasClass( 'open' ) ) {
+                section.toggleClass( 'open' );
+                content.slideUp( api.Panel.prototype.defaultExpandedArguments.duration );
+            } else {
+                content.slideDown( api.Panel.prototype.defaultExpandedArguments.duration );
+                section.toggleClass( 'open' );
             }
         });
@@ -1125 +1849 @@
         });
 
+        // Create Settings
         $.each( api.settings.settings, function( id, data ) {
             api.create( id, id, data.value, {
@@ -1132 +1857 @@
         });
 
+        // Create Panels
+        $.each( api.settings.panels, function ( id, data ) {
+            var constructor = api.panelConstructor[ data.type ] || api.Panel,
+                panel;
+
+            panel = new constructor( id, {
+                params: data
+            } );
+            api.panel.add( id, panel );
+        });
+
+        // Create Sections
+        $.each( api.settings.sections, function ( id, data ) {
+            var constructor = api.sectionConstructor[ data.type ] || api.Section,
+                section;
+
+            section = new constructor( id, {
+                params: data
+            } );
+            api.section.add( id, section );
+        });
+
+        // Create Controls
         $.each( api.settings.controls, function( id, data ) {
             var constructor = api.controlConstructor[ data.type ] || api.Control,
                 control;
 
-            control = api.control.add( id, new constructor( id, {
+            control = new constructor( id, {
                 params: data,
                 previewer: api.previewer
-            } ) );
+            } );
+            api.control.add( id, control );
         });
+
+        // Focus the autofocused element
+        _.each( [ 'panel', 'section', 'control' ], function ( type ) {
+            var instance, id = api.settings.autofocus[ type ];
+            if ( id && api[ type ]( id ) ) {
+                instance = api[ type ]( id );
+                // Wait until the element is embedded in the DOM
+                instance.deferred.ready.done( function () {
+                    // Wait until the preview has activated and so active panels, sections, controls have been set
+                    api.previewer.deferred.active.done( function () {
+                        instance.focus();
+                    });
+                });
+            }
+        });
+
+        /**
+         * Sort panels, sections, controls by priorities. Hide empty sections and panels.
+         */
+        api.reflowPaneContents = _.bind( function () {
+
+            var appendContainer, activeElement, rootContainers, rootNodes = [], wasReflowed = false;
+
+            if ( document.activeElement ) {
+                activeElement = $( document.activeElement );
+            }
+
+            // Sort the sections within each panel
+            api.panel.each( function ( panel ) {
+                var sections = panel.sections(),
+                    sectionContainers = _.pluck( sections, 'container' );
+                rootNodes.push( panel );
+                appendContainer = panel.container.find( 'ul:first' );
+                if ( ! areElementListsEqual( sectionContainers, appendContainer.children( '[id]' ) ) ) {
+                    _( sections ).each( function ( section ) {
+                        appendContainer.append( section.container );
+                    } );
+                    wasReflowed = true;
+                }
+            } );
+
+            // Sort the controls within each section
+            api.section.each( function ( section ) {
+                var controls = section.controls(),
+                    controlContainers = _.pluck( controls, 'container' );
+                if ( ! section.panel() ) {
+                    rootNodes.push( section );
+                }
+                appendContainer = section.container.find( 'ul:first' );
+                if ( ! areElementListsEqual( controlContainers, appendContainer.children( '[id]' ) ) ) {
+                    _( controls ).each( function ( control ) {
+                        appendContainer.append( control.container );
+                    } );
+                    wasReflowed = true;
+                }
+            } );
+
+            // Sort the root panels and sections
+            rootNodes.sort( function ( a, b ) {
+                return a.priority() - b.priority();
+            } );
+            rootContainers = _.pluck( rootNodes, 'container' );
+            appendContainer = $( '#customize-theme-controls' ).children( 'ul' ); // @todo This should be defined elsewhere, and to be configurable
+            if ( ! areElementListsEqual( rootContainers, appendContainer.children() ) ) {
+                _( rootNodes ).each( function ( rootNode ) {
+                    appendContainer.append( rootNode.container );
+                } );
+                wasReflowed = true;
+            }
+
+            // Now re-trigger the active Value callbacks to that the panels and sections can decide whether they can be rendered
+            api.panel.each( function ( panel ) {
+                var value = panel.active();
+                panel.active.callbacks.fireWith( panel.active, [ value, value ] );
+            } );
+            api.section.each( function ( section ) {
+                var value = section.active();
+                section.active.callbacks.fireWith( section.active, [ value, value ] );
+            } );
+
+            // Restore focus if there was a reflow and there was an active (focused) element
+            if ( wasReflowed && activeElement ) {
+                activeElement.focus();
+            }
+        }, api );
+        api.bind( 'ready', api.reflowPaneContents );
+        api.reflowPaneContents = _.debounce( api.reflowPaneContents, 100 );
+        $( [ api.panel, api.section, api.control ] ).each( function ( i, values ) {
+            values.bind( 'add', api.reflowPaneContents );
+            values.bind( 'change', api.reflowPaneContents );
+            values.bind( 'remove', api.reflowPaneContents );
+        } );
 
         // Check if preview url is valid and load the preview frame.
@@ -1206 +2047 @@
         });
 
+        // Go back to the top-level Customizer accordion.
+        $( '#customize-header-actions' ).on( 'click keydown', '.control-panel-back', function( event ) {
+            if ( isKeydownButNotEnterEvent( event ) ) {
+                return;
+            }
+
+            event.preventDefault(); // Keep this AFTER the key filter above
+            api.panel.each( function ( panel ) {
+                panel.collapse();
+            });
+        });
+
         closeBtn.keydown( function( event ) {
             if ( 9 === event.which ) // tab
@@ -1220 +2073 @@
 
         $('.collapse-sidebar').on( 'click keydown', function( event ) {
-            if ( event.type === 'keydown' &&  13 !== event.which ) // enter
+            if ( isKeydownButNotEnterEvent( event ) ) {
                 return;
+            }
 
             overlay.toggleClass( 'collapsed' ).toggleClass( 'expanded' );

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

@@ -405 +405 @@
      */
     api.Widgets.WidgetControl = api.Control.extend({
+        defaultExpandedArguments: {
+            duration: 'fast'
+        },
+
+        initialize: function ( id, options ) {
+            var control = this;
+            api.Control.prototype.initialize.call( control, id, options );
+            control.expanded = new api.Value();
+            control.expandedArgumentsQueue = [];
+            control.expanded.bind( function ( expanded ) {
+                var args = control.expandedArgumentsQueue.shift();
+                args = $.extend( {}, control.defaultExpandedArguments, args );
+                control.onChangeExpanded( expanded, args );
+            });
+            control.expanded.set( false );
+        },
+
         /**
          * Set up the control
@@ -530 +547 @@
                     return;
                 }
-                self.toggleForm();
+                self.expanded( ! self.expanded() );
             } );
 
@@ -536 +553 @@
             $closeBtn.on( 'click', function( e ) {
                 e.preventDefault();
-                self.collapseForm();
+                self.collapse();
                 self.container.find( '.widget-top .widget-action:first' ).focus(); // keyboard accessibility
             } );
@@ -778 +795 @@
          *
          * @param {Boolean} active
-         */
-        toggle: function ( active ) {
+         * @param {Object} args
+         */
+        onChangeActive: function ( active, args ) {
+            // Note: there is a second 'args' parameter being passed, merged on top of this.defaultActiveArguments
             this.container.toggleClass( 'widget-rendered', active );
+            if ( args.completeCallback ) {
+                args.completeCallback();
+            }
         },
 
@@ -1102 +1124 @@
          */
         expandControlSection: function() {
-            var $section = this.container.closest( '.accordion-section' );
-
-            if ( ! $section.hasClass( 'open' ) ) {
-                $section.find( '.accordion-section-title:first' ).trigger( 'click' );
-            }
-        },
+            api.Control.prototype.expand.call( this );
+        },
+
+        /**
+         * @param {Boolean} expanded
+         * @param {Object} [params]
+         * @returns {Boolean} false if state already applied
+         */
+        _toggleExpanded: api.Section.prototype._toggleExpanded,
+
+        /**
+         * @param {Object} [params]
+         * @returns {Boolean} false if already expanded
+         */
+        expand: api.Section.prototype.expand,
 
         /**
          * Expand the widget form control
+         *
+         * @deprecated alias of expand()
          */
         expandForm: function() {
-            this.toggleForm( true );
-        },
+            this.expand();
+        },
+
+        /**
+         * @param {Object} [params]
+         * @returns {Boolean} false if already collapsed
+         */
+        collapse: api.Section.prototype.collapse,
 
         /**
          * Collapse the widget form control
+         *
+         * @deprecated alias of expand()
          */
         collapseForm: function() {
-            this.toggleForm( false );
+            this.collapse();
         },
 
@@ -1126 +1167 @@
          * Expand or collapse the widget control
          *
+         * @deprecated this is poor naming, and it is better to directly set control.expanded( showOrHide )
+         *
          * @param {boolean|undefined} [showOrHide] If not supplied, will be inverse of current visibility
          */
         toggleForm: function( showOrHide ) {
-            var self = this, $widget, $inside, complete;
+            if ( typeof showOrHide === 'undefined' ) {
+                showOrHide = ! this.expanded();
+            }
+            this.expanded( showOrHide );
+        },
+
+        /**
+         * Respond to change in the expanded state.
+         *
+         * @param {Boolean} expanded
+         * @param {Object} args  merged on top of this.defaultActiveArguments
+         */
+        onChangeExpanded: function ( expanded, args ) {
+            var self = this, $widget, $inside, complete, prevComplete;
+
+            // If the expanded state is unchanged only manipulate container expanded states
+            if ( args.unchanged ) {
+                if ( expanded ) {
+                    api.Control.prototype.expand.call( self, {
+                        completeCallback:  args.completeCallback
+                    });
+                }
+                return;
+            }
 
             $widget = this.container.find( 'div.widget:first' );
             $inside = $widget.find( '.widget-inside:first' );
-            if ( typeof showOrHide === 'undefined' ) {
-                showOrHide = ! $inside.is( ':visible' );
-            }
-
-            // Already expanded or collapsed, so noop
-            if ( $inside.is( ':visible' ) === showOrHide ) {
-                return;
-            }
-
-            if ( showOrHide ) {
+
+            if ( expanded ) {
+
+                self.expandControlSection();
+
                 // Close all other widget controls before expanding this one
                 api.control.each( function( otherControl ) {
                     if ( self.params.type === otherControl.params.type && self !== otherControl ) {
-                        otherControl.collapseForm();
+                        otherControl.collapse();
                     }
                 } );
@@ -1155 +1216 @@
                     self.container.trigger( 'expanded' );
                 };
+                if ( args.completeCallback ) {
+                    prevComplete = complete;
+                    complete = function () {
+                        prevComplete();
+                        args.completeCallback();
+                    };
+                }
 
                 if ( self.params.is_wide ) {
-                    $inside.fadeIn( 'fast', complete );
+                    $inside.fadeIn( args.duration, complete );
                 } else {
-                    $inside.slideDown( 'fast', complete );
+                    $inside.slideDown( args.duration, complete );
                 }
 
@@ -1165 +1233 @@
                 self.container.addClass( 'expanding' );
             } else {
+
                 complete = function() {
                     self.container.removeClass( 'collapsing' );
@@ -1170 +1239 @@
                     self.container.trigger( 'collapsed' );
                 };
+                if ( args.completeCallback ) {
+                    prevComplete = complete;
+                    complete = function () {
+                        prevComplete();
+                        args.completeCallback();
+                    };
+                }
 
                 self.container.trigger( 'collapse' );
@@ -1175 +1251 @@
 
                 if ( self.params.is_wide ) {
-                    $inside.fadeOut( 'fast', complete );
+                    $inside.fadeOut( args.duration, complete );
                 } else {
-                    $inside.slideUp( 'fast', function() {
+                    $inside.slideUp( args.duration, function() {
                         $widget.css( { width:'', margin:'' } );
                         complete();
@@ -1183 +1259 @@
                 }
             }
-        },
-
-        /**
-         * Expand the containing sidebar section, expand the form, and focus on
-         * the first input in the control
-         */
-        focus: function() {
-            this.expandControlSection();
-            this.expandForm();
-            this.container.find( '.widget-content :focusable:first' ).focus();
         },
 
@@ -1305 +1371 @@
      */
     api.Widgets.SidebarControl = api.Control.extend({
+
         /**
          * Set up the control
@@ -1326 +1393 @@
 
             this.setting.bind( function( newWidgetIds, oldWidgetIds ) {
-                var widgetFormControls, $sidebarWidgetsAddControl, finalControlContainers, removedWidgetIds;
+                var widgetFormControls, removedWidgetIds, priority;
 
                 removedWidgetIds = _( oldWidgetIds ).difference( newWidgetIds );
@@ -1351 +1418 @@
                     var aIndex = _.indexOf( newWidgetIds, a.params.widget_id ),
                         bIndex = _.indexOf( newWidgetIds, b.params.widget_id );
-
-                    if ( aIndex === bIndex ) {
-                        return 0;
-                    }
-
-                    return aIndex < bIndex ? -1 : 1;
-                } );
-
-                // Append the controls to put them in the right order
-                finalControlContainers = _( widgetFormControls ).map( function( widgetFormControls ) {
-                    return widgetFormControls.container[0];
-                } );
-
-                $sidebarWidgetsAddControl = self.$sectionContent.find( '.customize-control-sidebar_widgets' );
-                $sidebarWidgetsAddControl.before( finalControlContainers );
+                    return aIndex - bIndex;
+                });
+
+                priority = 0;
+                _( widgetFormControls ).each( function ( control ) {
+                    control.priority( priority );
+                    control.section( self.section() );
+                    priority += 1;
+                });
+                self.priority( priority ); // Make sure sidebar control remains at end
 
                 // Re-sort widget form controls (including widgets form other sidebars newly moved here)
@@ -1435 +1497 @@
             self.active.bind( function ( active ) {
                 registeredSidebar.set( 'is_rendered', active );
-            } );
-        },
-
-        /**
-         * Show the sidebar section when it becomes visible.
-         *
-         * Overrides api.Control.toggle()
-         *
-         * @param {Boolean} active
-         */
-        toggle: function ( active ) {
-            var $section, sectionSelector;
-
-            sectionSelector = '#accordion-section-sidebar-widgets-' + this.params.sidebar_id;
-            $section = $( sectionSelector );
-
-            if ( active ) {
-                $section.stop().slideDown( function() {
-                    $( this ).css( 'height', 'auto' ); // so that the .accordion-section-content won't overflow
-                } );
-
-            } else {
-                // Make sure that hidden sections get closed first
-                if ( $section.hasClass( 'open' ) ) {
-                    // it would be nice if accordionSwitch() in accordion.js was public
-                    $section.find( '.accordion-section-title' ).trigger( 'click' );
-                }
-
-                $section.stop().slideUp();
-            }
+                api.section( self.section.get() ).active( active );
+            } );
+            api.section( self.section.get() ).active( self.active() );
         },
 
@@ -1501 +1536 @@
                 accept: '.customize-control-widget_form',
                 over: function() {
-                    if ( ! self.$controlSection.hasClass( 'open' ) ) {
-                        self.$controlSection.addClass( 'open' );
-                        self.$sectionContent.toggle( false ).slideToggle( 150, function() {
-                            self.$sectionContent.sortable( 'refreshPositions' );
-                        } );
-                    }
+                    var section = api.section( self.section.get() );
+                    section.expand({
+                        allowMultiple: true, // Prevent the section being dragged from to be collapsed
+                        completeCallback: function () {
+                            // @todo It is not clear when refreshPositions should be called on which sections, or if it is even needed
+                            api.section.each( function ( otherSection ) {
+                                if ( otherSection.container.find( '.customize-control-sidebar_widgets' ).length ) {
+                                    otherSection.container.find( '.accordion-section-content:first' ).sortable( 'refreshPositions' );
+                                }
+                            } );
+                        }
+                    });
                 }
             });
@@ -1549 +1590 @@
          */
         _applyCardinalOrderClassNames: function() {
-            this.$sectionContent.find( '.customize-control-widget_form' )
-                .removeClass( 'first-widget' )
-                .removeClass( 'last-widget' )
-                .find( '.move-widget-down, .move-widget-up' ).prop( 'tabIndex', 0 );
-
-            this.$sectionContent.find( '.customize-control-widget_form:first' )
+            var widgetControls = [];
+            _.each( this.setting(), function ( widgetId ) {
+                var widgetControl = api.Widgets.getWidgetFormControlForWidget( widgetId );
+                if ( widgetControl ) {
+                    widgetControls.push( widgetControl );
+                }
+            });
+
+            if ( ! widgetControls.length ) {
+                return;
+            }
+
+            $( widgetControls ).each( function () {
+                $( this.container )
+                    .removeClass( 'first-widget' )
+                    .removeClass( 'last-widget' )
+                    .find( '.move-widget-down, .move-widget-up' ).prop( 'tabIndex', 0 );
+            });
+
+            _.first( widgetControls ).container
                 .addClass( 'first-widget' )
                 .find( '.move-widget-up' ).prop( 'tabIndex', -1 );
 
-            this.$sectionContent.find( '.customize-control-widget_form:last' )
+            _.last( widgetControls ).container
                 .addClass( 'last-widget' )
                 .find( '.move-widget-down' ).prop( 'tabIndex', -1 );
@@ -1572 +1627 @@
          *
          * @param {Boolean} showOrHide to enable/disable reordering
+         *
+         * @todo We should have a reordering state instead and rename this to onChangeReordering
          */
         toggleReordering: function( showOrHide ) {
@@ -1585 +1642 @@
             if ( showOrHide ) {
                 _( this.getWidgetFormControls() ).each( function( formControl ) {
-                    formControl.collapseForm();
+                    formControl.collapse();
                 } );
 
@@ -1620 +1677 @@
          */
         addWidget: function( widgetId ) {
-            var self = this, controlHtml, $widget, controlType = 'widget_form', $control, controlConstructor,
+            var self = this, controlHtml, $widget, controlType = 'widget_form', controlContainer, controlConstructor,
                 parsedWidgetId = parseWidgetId( widgetId ),
                 widgetNumber = parsedWidgetId.number,
@@ -1652 +1709 @@
             $widget = $( controlHtml );
 
-            $control = $( '<li/>' )
+            controlContainer = $( '<li/>' )
                 .addClass( 'customize-control' )
                 .addClass( 'customize-control-' + controlType )
@@ -1658 +1715 @@
 
             // Remove icon which is visible inside the panel
-            $control.find( '> .widget-icon' ).remove();
+            controlContainer.find( '> .widget-icon' ).remove();
 
             if ( widget.get( 'is_multi' ) ) {
-                $control.find( 'input[name="widget_number"]' ).val( widgetNumber );
-                $control.find( 'input[name="multi_number"]' ).val( widgetNumber );
-            }
-
-            widgetId = $control.find( '[name="widget-id"]' ).val();
-
-            $control.hide(); // to be slid-down below
+                controlContainer.find( 'input[name="widget_number"]' ).val( widgetNumber );
+                controlContainer.find( 'input[name="multi_number"]' ).val( widgetNumber );
+            }
+
+            widgetId = controlContainer.find( '[name="widget-id"]' ).val();
+
+            controlContainer.hide(); // to be slid-down below
 
             settingId = 'widget_' + widget.get( 'id_base' );
@@ -1673 +1730 @@
                 settingId += '[' + widgetNumber + ']';
             }
-            $control.attr( 'id', 'customize-control-' + settingId.replace( /\]/g, '' ).replace( /\[/g, '-' ) );
-
-            this.container.after( $control );
+            controlContainer.attr( 'id', 'customize-control-' + settingId.replace( /\]/g, '' ).replace( /\[/g, '-' ) );
 
             // Only create setting if it doesn't already exist (if we're adding a pre-existing inactive widget)
@@ -1693 +1748 @@
                         'default': settingId
                     },
+                    content: controlContainer,
                     sidebar_id: self.params.sidebar_id,
                     widget_id: widgetId,
@@ -1732 +1788 @@
             }
 
-            $control.slideDown( function() {
+            controlContainer.slideDown( function() {
                 if ( isExistingWidget ) {
-                    widgetFormControl.expandForm();
+                    widgetFormControl.expand();
                     widgetFormControl.updateWidget( {
                         instance: widgetFormControl.setting(),

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

@@ -75 +75 @@
 
     /**
+     * @deprecated It is better to just call the json() method
      * @access public
      * @var array
@@ -219 +220 @@
 
         $this->json['type']        = $this->type;
+        $this->json['priority']    = $this->priority;
+        $this->json['active']      = $this->active();
+        $this->json['section']     = $this->section;
+        $this->json['content']     = $this->get_content();
         $this->json['label']       = $this->label;
         $this->json['description'] = $this->description;
-        $this->json['active']      = $this->active();
+    }
+
+    /**
+     * Get the data to export to the client via JSON.
+     *
+     * @since 4.1.0
+     *
+     * @return array
+     */
+    public function json() {
+        $this->to_json();
+        return $this->json;
     }
 
@@ -242 +258 @@
 
         return true;
+    }
+
+    /**
+     * Get the control's content for insertion into the Customizer pane.
+     *
+     * @since 4.1.0
+     *
+     * @return string
+     */
+    public final function get_content() {
+        ob_start();
+        $this->maybe_render();
+        $template = trim( ob_get_contents() );
+        ob_end_clean();
+        return $template;
     }
 
@@ -1074 +1105 @@
  * Widget Area Customize Control Class
  *
+ * @since 3.9.0
  */
 class WP_Widget_Area_Customize_Control extends WP_Customize_Control {
@@ -1115 +1147 @@
 /**
  * Widget Form Customize Control Class
+ *
+ * @since 3.9.0
  */
 class WP_Widget_Form_Customize_Control extends WP_Customize_Control {

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

@@ -499 +499 @@
             'values'  => array(),
             'channel' => wp_unslash( $_POST['customize_messenger_channel'] ),
+            'activePanels' => array(),
+            'activeSections' => array(),
             'activeControls' => array(),
         );
@@ -511 +513 @@
         foreach ( $this->settings as $id => $setting ) {
             $settings['values'][ $id ] = $setting->js_value();
+        }
+        foreach ( $this->panels as $id => $panel ) {
+            $settings['activePanels'][ $id ] = $panel->active();
+        }
+        foreach ( $this->sections as $id => $section ) {
+            $settings['activeSections'][ $id ] = $section->active();
         }
         foreach ( $this->controls as $id => $control ) {
@@ -912 +920 @@
             if ( ! $section->panel ) {
                 // Top-level section.
-                $sections[] = $section;
+                $sections[ $section->id ] = $section;
             } else {
                 // This section belongs to a panel.
                 if ( isset( $this->panels [ $section->panel ] ) ) {
-                    $this->panels[ $section->panel ]->sections[] = $section;
+                    $this->panels[ $section->panel ]->sections[ $section->id ] = $section;
                 }
             }
@@ -933 +941 @@
             }
 
-            usort( $panel->sections, array( $this, '_cmp_priority' ) );
-            $panels[] = $panel;
+            uasort( $panel->sections, array( $this, '_cmp_priority' ) );
+            $panels[ $panel->id ] = $panel;
         }
         $this->panels = $panels;

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

@@ -84 +84 @@
 
     /**
+     * @since 4.1.0
+     * @access public
+     * @var string
+     */
+    public $type;
+
+    /**
+     * Callback.
+     *
+     * @since 4.1.0
+     * @access public
+     *
+     * @see WP_Customize_Section::active()
+     *
+     * @var callable Callback is called with one argument, the instance of
+     *               WP_Customize_Section, and returns bool to indicate whether
+     *               the section is active (such as it relates to the URL
+     *               currently being previewed).
+     */
+    public $active_callback = '';
+
+    /**
      * Constructor.
      *
@@ -104 +126 @@
         $this->manager = $manager;
         $this->id = $id;
+        if ( empty( $this->active_callback ) ) {
+            $this->active_callback = array( $this, 'active_callback' );
+        }
 
         $this->sections = array(); // Users cannot customize the $sections array.
 
         return $this;
+    }
+
+    /**
+     * Check whether panel is active to current Customizer preview.
+     *
+     * @since 4.1.0
+     * @access public
+     *
+     * @return bool Whether the panel is active to the current preview.
+     */
+    public final function active() {
+        $panel = $this;
+        $active = call_user_func( $this->active_callback, $this );
+
+        /**
+         * Filter response of WP_Customize_Panel::active().
+         *
+         * @since 4.1.0
+         *
+         * @param bool                 $active  Whether the Customizer panel is active.
+         * @param WP_Customize_Panel $panel WP_Customize_Panel instance.
+         */
+        $active = apply_filters( 'customize_panel_active', $active, $panel );
+
+        return $active;
+    }
+
+    /**
+     * Default callback used when invoking WP_Customize_Panel::active().
+     *
+     * Subclasses can override this with their specific logic, or they may
+     * provide an 'active_callback' argument to the constructor.
+     *
+     * @since 4.1.0
+     * @access public
+     *
+     * @return bool Always true.
+     */
+    public function active_callback() {
+        return true;
+    }
+
+    /**
+     * Gather the parameters passed to client JavaScript via JSON.
+     *
+     * @since 4.1.0
+     *
+     * @return array The array to be exported to the client as JSON
+     */
+    public function json() {
+        $array = wp_array_slice_assoc( (array) $this, array( 'title', 'description', 'priority', 'type' ) );
+        $array['content'] = $this->get_content();
+        $array['active'] = $this->active();
+        return $array;
     }
 
@@ -128 +207 @@
 
         return true;
+    }
+
+    /**
+     * Get the panel's content template for insertion into the Customizer pane.
+     *
+     * @since 4.1.0
+     *
+     * @return string
+     */
+    public final function get_content() {
+        ob_start();
+        $this->maybe_render();
+        $template = trim( ob_get_contents() );
+        ob_end_clean();
+        return $template;
     }
 
@@ -190 +284 @@
     protected function render_content() {
         ?>
-        <li class="accordion-section control-section<?php if ( empty( $this->description ) ) echo ' cannot-expand'; ?>">
+        <li class="panel-meta accordion-section control-section<?php if ( empty( $this->description ) ) { echo ' cannot-expand'; } ?>">
             <div class="accordion-section-title" tabindex="0">
                 <span class="preview-notice"><?php
@@ -204 +298 @@
         </li>
         <?php
-        foreach ( $this->sections as $section ) {
-            $section->maybe_render();
-        }
     }
 }

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

@@ -93 +93 @@
 
     /**
+     * @since 4.1.0
+     * @access public
+     * @var string
+     */
+    public $type;
+
+    /**
+     * Callback.
+     *
+     * @since 4.1.0
+     * @access public
+     *
+     * @see WP_Customize_Section::active()
+     *
+     * @var callable Callback is called with one argument, the instance of
+     *               WP_Customize_Section, and returns bool to indicate whether
+     *               the section is active (such as it relates to the URL
+     *               currently being previewed).
+     */
+    public $active_callback = '';
+
+    /**
      * Constructor.
      *
@@ -106 +128 @@
         $keys = array_keys( get_object_vars( $this ) );
         foreach ( $keys as $key ) {
-            if ( isset( $args[ $key ] ) )
+            if ( isset( $args[ $key ] ) ) {
                 $this->$key = $args[ $key ];
+            }
         }
 
         $this->manager = $manager;
         $this->id = $id;
+        if ( empty( $this->active_callback ) ) {
+            $this->active_callback = array( $this, 'active_callback' );
+        }
 
         $this->controls = array(); // Users cannot customize the $controls array.
 
         return $this;
+    }
+
+    /**
+     * Check whether section is active to current Customizer preview.
+     *
+     * @since 4.1.0
+     * @access public
+     *
+     * @return bool Whether the section is active to the current preview.
+     */
+    public final function active() {
+        $section = $this;
+        $active = call_user_func( $this->active_callback, $this );
+
+        /**
+         * Filter response of WP_Customize_Section::active().
+         *
+         * @since 4.1.0
+         *
+         * @param bool                 $active  Whether the Customizer section is active.
+         * @param WP_Customize_Section $section WP_Customize_Section instance.
+         */
+        $active = apply_filters( 'customize_section_active', $active, $section );
+
+        return $active;
+    }
+
+    /**
+     * Default callback used when invoking WP_Customize_Section::active().
+     *
+     * Subclasses can override this with their specific logic, or they may
+     * provide an 'active_callback' argument to the constructor.
+     *
+     * @since 4.1.0
+     * @access public
+     *
+     * @return bool Always true.
+     */
+    public function active_callback() {
+        return true;
+    }
+
+    /**
+     * Gather the parameters passed to client JavaScript via JSON.
+     *
+     * @since 4.1.0
+     *
+     * @return array The array to be exported to the client as JSON
+     */
+    public function json() {
+        $array = wp_array_slice_assoc( (array) $this, array( 'title', 'description', 'priority', 'panel', 'type' ) );
+        $array['content'] = $this->get_content();
+        $array['active'] = $this->active();
+        return $array;
     }
 
@@ -127 +207 @@
      */
     public final function check_capabilities() {
-        if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) )
+        if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) ) {
             return false;
-
-        if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) )
+        }
+
+        if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) ) {
             return false;
+        }
 
         return true;
@@ -137 +219 @@
 
     /**
+     * Get the section's content template for insertion into the Customizer pane.
+     *
+     * @since 4.1.0
+     *
+     * @return string
+     */
+    public final function get_content() {
+        ob_start();
+        $this->maybe_render();
+        $template = trim( ob_get_contents() );
+        ob_end_clean();
+        return $template;
+    }
+
+    /**
      * Check capabilities and render the section.
      *
@@ -142 +239 @@
      */
     public final function maybe_render() {
-        if ( ! $this->check_capabilities() )
+        if ( ! $this->check_capabilities() ) {
             return;
+        }
 
         /**
@@ -173 +271 @@
     protected function render() {
         $classes = 'control-section accordion-section';
-        if ( $this->panel ) {
-            $classes .= ' control-subsection';
-        }
         ?>
         <li id="accordion-section-<?php echo esc_attr( $this->id ); ?>" class="<?php echo esc_attr( $classes ); ?>">
@@ -184 +279 @@
             <ul class="accordion-section-content">
                 <?php if ( ! empty( $this->description ) ) : ?>
-                <li><p class="description customize-section-description"><?php echo $this->description; ?></p></li>
+                    <li class="customize-section-description-container">
+                        <p class="description customize-section-description"><?php echo $this->description; ?></p>
+                    </li>
                 <?php endif; ?>
-                <?php
-                foreach ( $this->controls as $control )
-                    $control->maybe_render();
-                ?>
             </ul>
         </li>

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

@@ -185 +185 @@
 
             // Bail if the sanitized value is null or unchanged.
-            if ( null === to || _.isEqual( from, to ) )
+            if ( null === to || _.isEqual( from, to ) ) {
                 return this;
+            }
 
             this._value = to;

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

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

trunk/tests/qunit/index.html

@@ -9 +9 @@
   <script src="../../src/wp-includes/js/backbone.min.js"></script>
   <script src="../../src/wp-includes/js/zxcvbn.min.js"></script>
-    
+
   <!-- QUnit -->
   <link rel="stylesheet" href="vendor/qunit.css" type="text/css" media="screen" />
@@ -29 +29 @@
     <!-- Tested files -->
     <script src="../../src/wp-admin/js/password-strength-meter.js"></script>
+    <script src="../../src/wp-includes/js/customize-base.js"></script>
     <script src="../../src/wp-includes/js/customize-models.js"></script>
     <script src="../../src/wp-includes/js/shortcode.js"></script>
@@ -34 +35 @@
     <!-- Unit tests -->
     <script src="wp-admin/js/password-strength-meter.js"></script>
+    <script src="wp-admin/js/customize-base.js"></script>
     <script src="wp-admin/js/customize-header.js"></script>
     <script src="wp-includes/js/shortcode.js"></script>
@@ -39 +41 @@
 </body>
 </html>
-