Changeset 30102 for trunk/src/wp-includes/class-wp-customize-section.php

Timestamp:

10/29/2014 10:50:21 PM (12 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.

File:

• trunk/src/wp-includes/class-wp-customize-section.php (modified) (7 diffs)

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>