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

   1 <?php
   2 /**
   3  * WordPress Customize Section classes
   4  *
   5  * @package WordPress
   6  * @subpackage Customize
   7  * @since 3.4.0
   8  */
   9
  10 /**
  11  * Customize Section class.
  12  *
  13  * A UI container for controls, managed by the WP_Customize_Manager class.
  14  *
  15  * @since 3.4.0
  16  *
  17  * @see WP_Customize_Manager
  18  */
  19 class WP_Customize_Section {
  20
  21         /**
  22          * Incremented with each new class instantiation, then stored in $instance_number.
  23          *
  24          * Used when sorting two instances whose priorities are equal.
  25          *
  26          * @since 4.1.0
  27          *
  28          * @static
  29          * @access protected
  30          * @var int
  31          */
  32         protected static $instance_count = 0;
  33
  34         /**
  35          * Order in which this instance was created in relation to other instances.
  36          *
  37          * @since 4.1.0
  38          * @access public
  39          * @var int
  40          */
  41         public $instance_number;
  42
  43         /**
  44          * WP_Customize_Manager instance.
  45          *
  46          * @since 3.4.0
  47          * @access public
  48          * @var WP_Customize_Manager
  49          */
  50         public $manager;
  51
  52         /**
  53          * Unique identifier.
  54          *
  55          * @since 3.4.0
  56          * @access public
  57          * @var string
  58          */
  59         public $id;
  60
  61         /**
  62          * Priority of the section which informs load order of sections.
  63          *
  64          * @since 3.4.0
  65          * @access public
  66          * @var integer
  67          */
  68         public $priority = 160;
  69
  70         /**
  71          * Panel in which to show the section, making it a sub-section.
  72          *
  73          * @since 4.0.0
  74          * @access public
  75          * @var string
  76          */
  77         public $panel = '';
  78
  79         /**
  80          * Capability required for the section.
  81          *
  82          * @since 3.4.0
  83          * @access public
  84          * @var string
  85          */
  86         public $capability = 'edit_theme_options';
  87
  88         /**
  89          * Theme feature support for the section.
  90          *
  91          * @since 3.4.0
  92          * @access public
  93          * @var string|array
  94          */
  95         public $theme_supports = '';
  96
  97         /**
  98          * Title of the section to show in UI.
  99          *
 100          * @since 3.4.0
 101          * @access public
 102          * @var string
 103          */
 104         public $title = '';
 105
 106         /**
 107          * Description to show in the UI.
 108          *
 109          * @since 3.4.0
 110          * @access public
 111          * @var string
 112          */
 113         public $description = '';
 114
 115         /**
 116          * Customizer controls for this section.
 117          *
 118          * @since 3.4.0
 119          * @access public
 120          * @var array
 121          */
 122         public $controls;
 123
 124         /**
 125          * Type of this section.
 126          *
 127          * @since 4.1.0
 128          * @access public
 129          * @var string
 130          */
 131         public $type = 'default';
 132
 133         /**
 134          * Active callback.
 135          *
 136          * @since 4.1.0
 137          * @access public
 138          *
 139          * @see WP_Customize_Section::active()
 140          *
 141          * @var callable Callback is called with one argument, the instance of
 142          *               {@see WP_Customize_Section}, and returns bool to indicate
 143          *               whether the section is active (such as it relates to the URL
 144          *               currently being previewed).
 145          */
 146         public $active_callback = '';
 147
 148         /**
 149          * Constructor.
 150          *
 151          * Any supplied $args override class property defaults.
 152          *
 153          * @since 3.4.0
 154          *
 155          * @param WP_Customize_Manager $manager Customizer bootstrap instance.
 156          * @param string               $id      An specific ID of the section.
 157          * @param array                $args    Section arguments.
 158          */
 159         public function __construct( $manager, $id, $args = array() ) {
 160                 $keys = array_keys( get_object_vars( $this ) );
 161                 foreach ( $keys as $key ) {
 162                         if ( isset( $args[ $key ] ) ) {
 163                                 $this->$key = $args[ $key ];
 164                         }
 165                 }
 166
 167                 $this->manager = $manager;
 168                 $this->id = $id;
 169                 if ( empty( $this->active_callback ) ) {
 170                         $this->active_callback = array( $this, 'active_callback' );
 171                 }
 172                 self::$instance_count += 1;
 173                 $this->instance_number = self::$instance_count;
 174
 175                 $this->controls = array(); // Users cannot customize the $controls array.
 176         }
 177
 178         /**
 179          * Check whether section is active to current Customizer preview.
 180          *
 181          * @since 4.1.0
 182          * @access public
 183          *
 184          * @return bool Whether the section is active to the current preview.
 185          */
 186         final public function active() {
 187                 $section = $this;
 188                 $active = call_user_func( $this->active_callback, $this );
 189
 190                 /**
 191                  * Filter response of {@see WP_Customize_Section::active()}.
 192                  *
 193                  * @since 4.1.0
 194                  *
 195                  * @param bool                 $active  Whether the Customizer section is active.
 196                  * @param WP_Customize_Section $section {@see WP_Customize_Section} instance.
 197                  */
 198                 $active = apply_filters( 'customize_section_active', $active, $section );
 199
 200                 return $active;
 201         }
 202
 203         /**
 204          * Default callback used when invoking {@see WP_Customize_Section::active()}.
 205          *
 206          * Subclasses can override this with their specific logic, or they may provide
 207          * an 'active_callback' argument to the constructor.
 208          *
 209          * @since 4.1.0
 210          * @access public
 211          *
 212          * @return true Always true.
 213          */
 214         public function active_callback() {
 215                 return true;
 216         }
 217
 218         /**
 219          * Gather the parameters passed to client JavaScript via JSON.
 220          *
 221          * @since 4.1.0
 222          *
 223          * @return array The array to be exported to the client as JSON.
 224          */
 225         public function json() {
 226                 $array = wp_array_slice_assoc( (array) $this, array( 'id', 'description', 'priority', 'panel', 'type' ) );
 227                 $array['title'] = html_entity_decode( $this->title, ENT_QUOTES, get_bloginfo( 'charset' ) );
 228                 $array['content'] = $this->get_content();
 229                 $array['active'] = $this->active();
 230                 $array['instanceNumber'] = $this->instance_number;
 231
 232                 if ( $this->panel ) {
 233                         /* translators: &#9656; is the unicode right-pointing triangle, and %s is the section title in the Customizer */
 234                         $array['customizeAction'] = sprintf( __( 'Customizing &#9656; %s' ), esc_html( $this->manager->get_panel( $this->panel )->title ) );
 235                 } else {
 236                         $array['customizeAction'] = __( 'Customizing' );
 237                 }
 238
 239                 return $array;
 240         }
 241
 242         /**
 243          * Checks required user capabilities and whether the theme has the
 244          * feature support required by the section.
 245          *
 246          * @since 3.4.0
 247          *
 248          * @return bool False if theme doesn't support the section or user doesn't have the capability.
 249          */
 250         final public function check_capabilities() {
 251                 if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) ) {
 252                         return false;
 253                 }
 254
 255                 if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) ) {
 256                         return false;
 257                 }
 258
 259                 return true;
 260         }
 261
 262         /**
 263          * Get the section's content for insertion into the Customizer pane.
 264          *
 265          * @since 4.1.0
 266          *
 267          * @return string Contents of the section.
 268          */
 269         final public function get_content() {
 270                 ob_start();
 271                 $this->maybe_render();
 272                 return trim( ob_get_clean() );
 273         }
 274
 275         /**
 276          * Check capabilities and render the section.
 277          *
 278          * @since 3.4.0
 279          */
 280         final public function maybe_render() {
 281                 if ( ! $this->check_capabilities() ) {
 282                         return;
 283                 }
 284
 285                 /**
 286                  * Fires before rendering a Customizer section.
 287                  *
 288                  * @since 3.4.0
 289                  *
 290                  * @param WP_Customize_Section $this WP_Customize_Section instance.
 291                  */
 292                 do_action( 'customize_render_section', $this );
 293                 /**
 294                  * Fires before rendering a specific Customizer section.
 295                  *
 296                  * The dynamic portion of the hook name, `$this->id`, refers to the ID
 297                  * of the specific Customizer section to be rendered.
 298                  *
 299                  * @since 3.4.0
 300                  */
 301                 do_action( "customize_render_section_{$this->id}" );
 302
 303                 $this->render();
 304         }
 305
 306         /**
 307          * Render the section UI in a subclass.
 308          *
 309          * Sections are now rendered in JS by default, see {@see WP_Customize_Section::print_template()}.
 310          *
 311          * @since 3.4.0
 312          */
 313         protected function render() {}
 314
 315         /**
 316          * Render the section's JS template.
 317          *
 318          * This function is only run for section types that have been registered with
 319          * WP_Customize_Manager::register_section_type().
 320          *
 321          * @since 4.3.0
 322          * @access public
 323          *
 324          * @see WP_Customize_Manager::render_template()
 325          */
 326         public function print_template() {
 327         ?>
 328                 <script type="text/html" id="tmpl-customize-section-<?php echo $this->type; ?>">
 329                         <?php $this->render_template(); ?>
 330                 </script>
 331         <?php
 332         }
 333
 334         /**
 335          * An Underscore (JS) template for rendering this section.
 336          *
 337          * Class variables for this section class are available in the `data` JS object;
 338          * export custom variables by overriding WP_Customize_Section::json().
 339          *
 340          * @since 4.3.0
 341          * @access protected
 342          *
 343          * @see WP_Customize_Section::print_template()
 344          */
 345         protected function render_template() {
 346                 ?>
 347                 <li id="accordion-section-{{ data.id }}" class="accordion-section control-section control-section-{{ data.type }}">
 348                         <h3 class="accordion-section-title" tabindex="0">
 349                                 {{ data.title }}
 350                                 <span class="screen-reader-text"><?php _e( 'Press return or enter to open this section' ); ?></span>
 351                         </h3>
 352                         <ul class="accordion-section-content">
 353                                 <li class="customize-section-description-container">
 354                                         <div class="customize-section-title">
 355                                                 <button class="customize-section-back" tabindex="-1">
 356                                                         <span class="screen-reader-text"><?php _e( 'Back' ); ?></span>
 357                                                 </button>
 358                                                 <h3>
 359                                                         <span class="customize-action">
 360                                                                 {{{ data.customizeAction }}}
 361                                                         </span>
 362                                                         {{ data.title }}
 363                                                 </h3>
 364                                         </div>
 365                                         <# if ( data.description ) { #>
 366                                                 <div class="description customize-section-description">
 367                                                         {{{ data.description }}}
 368                                                 </div>
 369                                         <# } #>
 370                                 </li>
 371                         </ul>
 372                 </li>
 373                 <?php
 374         }
 375 }
 376
 377 /** WP_Customize_Themes_Section class */
 378 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-themes-section.php' );
 379
 380 /** WP_Customize_Sidebar_Section class */
 381 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-sidebar-section.php' );
 382
 383 /** WP_Customize_Nav_Menu_Section class */
 384 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-section.php' );
 385
 386 /** WP_Customize_New_Menu_Section class */
 387 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-new-menu-section.php' );