Ticket #28709: 28709.wip.2.diff

src/wp-admin/customize.php

@@ -160 +160 @@
                                 <?php endif; ?>
                         </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>
 
@@ -249 +245 @@
                 ),
                 '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() )
@@ -263 +261 @@
                 );
         }
 
-        // 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();
+                }
         }
 
         ?>

src/wp-admin/js/accordion.js

@@ -58 +58 @@
                 });
         });
 
-        var sectionContent = $( '.accordion-section-content' );
-
         /**
          * Close the current accordion section and open a new one.
          *
@@ -69 +67 @@
         function accordionSwitch ( el ) {
                 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' ) ) {
@@ -87 +85 @@
                         content.toggle( true ).slideToggle( 150 );
                 } 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' );
                 }
@@ -125 +123 @@
                 } else {
                         // Close all open sections in any accordion level.
                         siblings.removeClass( 'open' );
-                        siblings.find( sectionContent ).show().slideUp( 0 );
+                        siblings.find( '.accordion-section-content' ).show().slideUp( 0 );
                         content.show( 0, function() {
                                 position = content.offset().top;
                                 scroll = container.scrollTop();

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

@@ -1 +1 @@
 /* globals _wpCustomizeHeader, _wpMediaViewsL10n */
 (function( exports, $ ){
-        var api = wp.customize;
+        var bubbleChildValueChanges, api = wp.customize;
 
         /**
          * @constructor
@@ -31 +31 @@
         });
 
         /**
+         * Watch all changes to Value properties, and bubble changes to parent Values instance
+         *
+         * @param instance
+         */
+        bubbleChildValueChanges = function ( instance ) {
+                $.each( instance, function ( key, value ) {
+                        if ( value && value.extended && value.extended( api.Value ) ) {
+                                value.bind( function () {
+                                        if ( instance.parent ) {
+                                                instance.parent.trigger( 'change', instance );
+                                        }
+                                } );
+                        }
+                } );
+        };
+
+        /**
+         * @constructor
+         * @augments wp.customize.Class
+         */
+        api.Section = api.Class.extend({
+
+                /**
+                 * @param {String} id
+                 * @param {Array} options
+                 */
+                initialize: function ( id, options ) {
+                        var section = this;
+                        section.id = id;
+                        section.params = {};
+                        $.extend( section, options || {} );
+                        section.panel = new api.Value();
+                        section.container = $( section.params.content );
+                        section.priority = new api.Value( section.params.priority || 100 );
+                        section.panel.bind( function ( id ) {
+                                $( section.container ).toggleClass( 'control-subsection', !! id );
+                        });
+                        section.panel.set( section.params.panel || '' );
+                        section.active = new api.Value( true ); // @todo pass from params; value is whether sections is not empty
+                        section.active.bind( function ( active ) {
+                                section.toggle( active );
+                        } );
+                        section.toggle( section.active() );
+                        bubbleChildValueChanges( this );
+                },
+
+                /**
+                 *
+                 */
+                embed: function ( readyCallback ) {
+                        var panel_id,
+                                section = this;
+
+                        panel_id = this.panel.get();
+                        if ( ! panel_id ) {
+                                $( '#customize-theme-controls > ul' ).append( section.container );
+                                readyCallback();
+                        } else {
+                                api.panel( panel_id, function ( panel ) {
+                                        panel.embed();
+                                        panel.container.find( 'ul:first' ).append( section.container );
+                                        readyCallback();
+                                } );
+                        }
+                },
+
+                /**
+                 * Get the controls that are associated with this section.
+                 *
+                 * @returns {Array}
+                 */
+                controls: function () {
+                        var section = this,
+                                controls = [];
+                        api.control.each( function ( control ) {
+                                if ( control.section.get() === section.id ) {
+                                        controls.push( control );
+                                }
+                        } );
+                        controls.sort( function ( a, b ) {
+                                return a.priority() - b.priority();
+                        } );
+                        return controls;
+                },
+
+                /**
+                 * Callback for change to the section's active state.
+                 *
+                 * Override function for custom behavior for the section being active/inactive.
+                 *
+                 * @param {Boolean} active
+                 */
+                toggle: function ( active ) {
+                        if ( active ) {
+                                this.container.slideDown();
+                        } else {
+                                this.container.slideUp();
+                        }
+                },
+
+                /**
+                 * Bring the containing panel into view and then expand this section and bring it into view
+                 */
+                focus: function () {
+                        throw new Error( 'Not implemented yet' );
+                }
+        });
+
+        /**
+         * @constructor
+         * @augments wp.customize.Class
+         */
+        api.Panel = api.Class.extend({
+                initialize: function ( id, options ) {
+                        var panel = this;
+                        panel.id = id;
+                        panel.params = {};
+                        $.extend( panel, options || {} );
+                        panel.priority = new api.Value( panel.params.priority || 160 ); // @todo What if the priority gets changed dynamically?
+                        panel.container = $( panel.params.content );
+                        panel.active = new api.Value( true ); // @todo pass from params; value is whether sections is not empty
+                        panel.active.bind( function ( active ) {
+                                panel.toggle( active );
+                        } );
+                        panel.toggle( panel.active() );
+                        bubbleChildValueChanges( this );
+                },
+
+                /**
+                 *
+                 */
+                embed: function ( readyCallback ) {
+                        $( '#customize-theme-controls > ul' ).append( this.container );
+                        if ( readyCallback ) {
+                                readyCallback();
+                        }
+                },
+
+                /**
+                 * Get the controls that are associated with this section.
+                 *
+                 * @returns {Array}
+                 */
+                sections: function () {
+                        var panel = this,
+                                sections = [];
+                        api.section.each( function ( section ) {
+                                if ( section.panel.get() === panel.id ) {
+                                        sections.push( section );
+                                }
+                        } );
+                        sections.sort( function ( a, b ) {
+                                return a.priority() - b.priority();
+                        } );
+                        return sections;
+                },
+
+                /**
+                 * Callback for change to the panel's active state.
+                 *
+                 * Override function for custom behavior for the control being active/inactive.
+                 *
+                 * @param {Boolean} active
+                 */
+                toggle: function ( active ) {
+                        if ( active ) {
+                                this.container.slideDown();
+                        } else {
+                                // @todo Need to first exit out of the Panel
+                                this.container.slideUp();
+                        }
+                }
+        });
+
+        /**
          * @constructor
          * @augments wp.customize.Class
          */
@@ -44 +219 @@
 
                         this.id = id;
                         this.selector = '#customize-control-' + id.replace( /\]/g, '' ).replace( /\[/g, '-' );
-                        this.container = $( this.selector );
+                        this.container = this.params.content ? $( this.params.content ) : $( this.selector );
+
+                        this.section = new api.Value( this.params.section );
+                        this.priority = new api.Value( this.params.priority || 10 );
                         this.active = new api.Value( this.params.active );
 
                         settings = $.map( this.params.settings, function( value ) {
@@ -60 +238 @@
                                 }
 
                                 control.setting = control.settings['default'] || null;
-                                control.ready();
+                                control.embed( function () {
+                                        control.ready();
+                                } );
                         }) );
 
                         control.elements = [];
@@ -74 +254 @@
 
                                 if ( node.is(':radio') ) {
                                         name = node.prop('name');
-                                        if ( radios[ name ] )
+                                        if ( radios[ name ] ) {
                                                 return;
+                                        }
 
                                         radios[ name ] = true;
                                         node = nodes.filter( '[name="' + name + '"]' );
@@ -93 +274 @@
                                 control.toggle( active );
                         } );
                         control.toggle( control.active() );
+
+                        bubbleChildValueChanges( this );
+                },
+
+                /**
+                 * @param {Function} [readyCallback] Callback to fire when the embedding is done.
+                 */
+                embed: function ( readyCallback ) {
+                        var section_id,
+                                control = this;
+
+                        section_id = control.section.get();
+                        if ( ! section_id ) {
+                                throw new Error( 'A control must have an associated section.' );
+                        }
+
+                        // Defer until the associated section is available
+                        api.section( section_id, function ( section ) {
+                                section.embed( function () {
+                                        section.container.find( 'ul:first' ).append( control.container );
+                                        readyCallback();
+                                } );
+                        } );
                 },
 
                 /**
@@ -101 +305 @@
                 ready: function() {},
 
                 /**
+                 * Bring the containing section and panel into view and then this control into view, focusing on the first input
+                 */
+                focus: function () {
+                        throw new Error( 'Not implemented yet' );
+                },
+
+                /**
                  * Callback for change to the control's active state.
                  *
                  * Override function for custom behavior for the control being active/inactive.
@@ -575 +786 @@
 
         // 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 });
 
         /**
          * @constructor
@@ -979 +1192 @@
                 image:  api.ImageControl,
                 header: api.HeaderControl
         };
+        api.panelConstructor = {};
+        api.sectionConstructor = {};
 
         $( function() {
                 api.settings = window._wpCustomizeSettings;
@@ -1091 +1306 @@
                         $.extend( this.nonce, nonce );
                 });
 
+                // Create Settings
                 $.each( api.settings.settings, function( id, data ) {
                         api.create( id, id, data.value, {
                                 transport: data.transport,
@@ -1098 +1314 @@
                         } );
                 });
 
+                // 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
+                // @todo factor this out
                 $.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 );
                 });
 
+                /**
+                 * Sort panels, sections, controls by priorities. Hide empty sections and panels.
+                 */
+                api.reflowPaneContents = _.bind( function () {
+
+                        var appendContainer, rootNodes = [];
+
+                        api.panel.each( function ( panel ) {
+                                rootNodes.push( panel );
+
+                                // Toggle display
+                                var activeCount = 0,
+                                        sections = panel.sections();
+                                _( sections ).each( function ( section ) {
+                                        if ( section.active && section.active() ) {
+                                                activeCount += 1;
+                                        }
+                                } );
+                                panel.toggle( 0 !== activeCount ); // @todo This is not sticking
+
+                                // Sort sections
+                                appendContainer = panel.container.find( 'ul:first' );
+                                _.chain( sections ).reverse().each( function ( section ) {
+                                        appendContainer.append( section.container );
+                                } );
+                        } );
+
+                        api.section.each( function ( section ) {
+                                var activeCount = 0,
+                                        controls = section.controls();
+                                _( controls ).each( function ( control ) {
+                                        if ( control.active && control.active() ) {
+                                                activeCount += 1;
+                                        }
+                                } );
+                                section.toggle( 0 !== activeCount );
+
+                                if ( ! section.panel() ) {
+                                        rootNodes.push( section );
+                                }
+
+                                // Sort controls
+                                appendContainer = section.container.find( 'ul:first' );
+                                _.chain( controls ).reverse().each( function ( control ) {
+                                        appendContainer.append( control.container );
+                                } );
+                        } );
+
+                        // Sort the root elements
+                        rootNodes.sort( function ( a, b ) {
+                                return a.priority() - b.priority();
+                        } );
+                        appendContainer = $( '#customize-theme-controls > ul' );
+                        _.chain( rootNodes ).each( function ( rootNode ) {
+                                appendContainer.append( rootNode.container );
+                        } );
+                }, api );
+                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 );
+                } );
+                api.bind( 'ready', api.reflowPaneContents );
+
                 // Check if preview url is valid and load the preview frame.
                 if ( api.previewer.previewUrl() ) {
                         api.previewer.refresh();

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

@@ -74 +74 @@
         public $input_attrs = array();
 
         /**
+         * @deprecated It is better to just call the json() method
          * @access public
          * @var array
          */
@@ -219 +220 @@
 
                 $this->json['type'] = $this->type;
                 $this->json['active'] = $this->active();
+                $this->json['section'] = $this->section;
+                $this->json['content'] = $this->get_content();
+        }
+
+        /**
+         * 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 +257 @@
         }
 
         /**
+         * 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;
+        }
+
+        /**
          * Check capabilities and render the control.
          *
          * @since 3.4.0

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

@@ -878 +878 @@
 
                         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;
                                 }
                         }
                 }
@@ -899 +899 @@
                                 continue;
                         }
 
-                        usort( $panel->sections, array( $this, '_cmp_priority' ) );
-                        $panels[] = $panel;
+                        uasort( $panel->sections, array( $this, '_cmp_priority' ) );
+                        $panels[ $panel->id ] = $panel;
                 }
                 $this->panels = $panels;
 

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

@@ -83 +83 @@
         public $sections;
 
         /**
+         * @since 4.1.0
+         * @access public
+         * @var string
+         */
+        public $type;
+
+        /**
          * Constructor.
          *
          * Any supplied $args override class property defaults.
@@ -110 +117 @@
         }
 
         /**
+         * 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();
+                return $array;
+        }
+
+        /**
          * Checks required user capabilities and whether the theme has the
          * feature support required by the panel.
          *
@@ -130 +150 @@
         }
 
         /**
+         * 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;
+        }
+
+        /**
          * Check capabilities and render the panel.
          *
          * @since 4.0.0
@@ -175 +210 @@
                                 <span class="screen-reader-text"><?php _e( 'Press return or enter to open this panel' ); ?></span>
                         </h3>
                         <ul class="accordion-sub-container control-panel-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
                                                         /* translators: %s is the site/panel title in the Customizer */
@@ -188 +223 @@
                                                 </div>
                                         <?php endif; ?>
                                 </li>
-                                <?php
-                                foreach ( $this->sections as $section ) {
-                                        $section->maybe_render();
-                                }
-                                ?>
+
                         </ul>
                 </li>
                 <?php

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

@@ -92 +92 @@
         public $controls;
 
         /**
+         * @since 4.1.0
+         * @access public
+         * @var string
+         */
+        public $type;
+
+        /**
          * Constructor.
          *
          * Any supplied $args override class property defaults.
@@ -118 +125 @@
         }
 
         /**
+         * 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();
+                return $array;
+        }
+
+        /**
          * Checks required user capabilities and whether the theme has the
          * feature support required by the section.
          *
@@ -136 +156 @@
         }
 
         /**
+         * 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.
          *
          * @since 3.4.0
@@ -172 +207 @@
          */
         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 ); ?>">
                         <h3 class="accordion-section-title" tabindex="0">
@@ -183 +215 @@
                         </h3>
                         <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>
                 <?php

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

@@ -183 +183 @@
                         to = this.validate( to );
 
                         // Bail if the sanitized value is null or unchanged.
-                        if ( null === to || this._value === to )
+                        if ( null === to || this._value === to ) { // @todo why bail if null?
                                 return this;
+                        }
 
                         this._value = to;