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          *               WP_Customize_Section, and returns bool to indicate whether
 143          *               the section is active (such as it relates to the URL currently
 144          *               being previewed).
 145          */
 146         public $active_callback = '';
 147
 148         /**
 149          * Show the description or hide it behind the help icon.
 150          *
 151          * @since 4.7.0
 152          * @access public
 153          *
 154          * @var bool Indicates whether the Section's description should be
 155          *           hidden behind a help icon ("?") in the Section header,
 156          *           similar to how help icons are displayed on Panels.
 157          */
 158         public $description_hidden = false;
 159
 160         /**
 161          * Constructor.
 162          *
 163          * Any supplied $args override class property defaults.
 164          *
 165          * @since 3.4.0
 166          *
 167          * @param WP_Customize_Manager $manager Customizer bootstrap instance.
 168          * @param string               $id      An specific ID of the section.
 169          * @param array                $args    Section arguments.
 170          */
 171         public function __construct( $manager, $id, $args = array() ) {
 172                 $keys = array_keys( get_object_vars( $this ) );
 173                 foreach ( $keys as $key ) {
 174                         if ( isset( $args[ $key ] ) ) {
 175                                 $this->$key = $args[ $key ];
 176                         }
 177                 }
 178
 179                 $this->manager = $manager;
 180                 $this->id = $id;
 181                 if ( empty( $this->active_callback ) ) {
 182                         $this->active_callback = array( $this, 'active_callback' );
 183                 }
 184                 self::$instance_count += 1;
 185                 $this->instance_number = self::$instance_count;
 186
 187                 $this->controls = array(); // Users cannot customize the $controls array.
 188         }
 189
 190         /**
 191          * Check whether section is active to current Customizer preview.
 192          *
 193          * @since 4.1.0
 194          * @access public
 195          *
 196          * @return bool Whether the section is active to the current preview.
 197          */
 198         final public function active() {
 199                 $section = $this;
 200                 $active = call_user_func( $this->active_callback, $this );
 201
 202                 /**
 203                  * Filters response of WP_Customize_Section::active().
 204                  *
 205                  * @since 4.1.0
 206                  *
 207                  * @param bool                 $active  Whether the Customizer section is active.
 208                  * @param WP_Customize_Section $section WP_Customize_Section instance.
 209                  */
 210                 $active = apply_filters( 'customize_section_active', $active, $section );
 211
 212                 return $active;
 213         }
 214
 215         /**
 216          * Default callback used when invoking WP_Customize_Section::active().
 217          *
 218          * Subclasses can override this with their specific logic, or they may provide
 219          * an 'active_callback' argument to the constructor.
 220          *
 221          * @since 4.1.0
 222          * @access public
 223          *
 224          * @return true Always true.
 225          */
 226         public function active_callback() {
 227                 return true;
 228         }
 229
 230         /**
 231          * Gather the parameters passed to client JavaScript via JSON.
 232          *
 233          * @since 4.1.0
 234          *
 235          * @return array The array to be exported to the client as JSON.
 236          */
 237         public function json() {
 238                 $array = wp_array_slice_assoc( (array) $this, array( 'id', 'description', 'priority', 'panel', 'type', 'description_hidden' ) );
 239                 $array['title'] = html_entity_decode( $this->title, ENT_QUOTES, get_bloginfo( 'charset' ) );
 240                 $array['content'] = $this->get_content();
 241                 $array['active'] = $this->active();
 242                 $array['instanceNumber'] = $this->instance_number;
 243
 244                 if ( $this->panel ) {
 245                         /* translators: &#9656; is the unicode right-pointing triangle, and %s is the section title in the Customizer */
 246                         $array['customizeAction'] = sprintf( __( 'Customizing &#9656; %s' ), esc_html( $this->manager->get_panel( $this->panel )->title ) );
 247                 } else {
 248                         $array['customizeAction'] = __( 'Customizing' );
 249                 }
 250
 251                 return $array;
 252         }
 253
 254         /**
 255          * Checks required user capabilities and whether the theme has the
 256          * feature support required by the section.
 257          *
 258          * @since 3.4.0
 259          *
 260          * @return bool False if theme doesn't support the section or user doesn't have the capability.
 261          */
 262         final public function check_capabilities() {
 263                 if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) ) {
 264                         return false;
 265                 }
 266
 267                 if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) ) {
 268                         return false;
 269                 }
 270
 271                 return true;
 272         }
 273
 274         /**
 275          * Get the section's content for insertion into the Customizer pane.
 276          *
 277          * @since 4.1.0
 278          *
 279          * @return string Contents of the section.
 280          */
 281         final public function get_content() {
 282                 ob_start();
 283                 $this->maybe_render();
 284                 return trim( ob_get_clean() );
 285         }
 286
 287         /**
 288          * Check capabilities and render the section.
 289          *
 290          * @since 3.4.0
 291          */
 292         final public function maybe_render() {
 293                 if ( ! $this->check_capabilities() ) {
 294                         return;
 295                 }
 296
 297                 /**
 298                  * Fires before rendering a Customizer section.
 299                  *
 300                  * @since 3.4.0
 301                  *
 302                  * @param WP_Customize_Section $this WP_Customize_Section instance.
 303                  */
 304                 do_action( 'customize_render_section', $this );
 305                 /**
 306                  * Fires before rendering a specific Customizer section.
 307                  *
 308                  * The dynamic portion of the hook name, `$this->id`, refers to the ID
 309                  * of the specific Customizer section to be rendered.
 310                  *
 311                  * @since 3.4.0
 312                  */
 313                 do_action( "customize_render_section_{$this->id}" );
 314
 315                 $this->render();
 316         }
 317
 318         /**
 319          * Render the section UI in a subclass.
 320          *
 321          * Sections are now rendered in JS by default, see WP_Customize_Section::print_template().
 322          *
 323          * @since 3.4.0
 324          */
 325         protected function render() {}
 326
 327         /**
 328          * Render the section's JS template.
 329          *
 330          * This function is only run for section types that have been registered with
 331          * WP_Customize_Manager::register_section_type().
 332          *
 333          * @since 4.3.0
 334          * @access public
 335          *
 336          * @see WP_Customize_Manager::render_template()
 337          */
 338         public function print_template() {
 339                 ?>
 340                 <script type="text/html" id="tmpl-customize-section-<?php echo $this->type; ?>">
 341                         <?php $this->render_template(); ?>
 342                 </script>
 343                 <?php
 344         }
 345
 346         /**
 347          * An Underscore (JS) template for rendering this section.
 348          *
 349          * Class variables for this section class are available in the `data` JS object;
 350          * export custom variables by overriding WP_Customize_Section::json().
 351          *
 352          * @since 4.3.0
 353          * @access protected
 354          *
 355          * @see WP_Customize_Section::print_template()
 356          */
 357         protected function render_template() {
 358                 ?>
 359                 <li id="accordion-section-{{ data.id }}" class="accordion-section control-section control-section-{{ data.type }}">
 360                         <h3 class="accordion-section-title" tabindex="0">
 361                                 {{ data.title }}
 362                                 <span class="screen-reader-text"><?php _e( 'Press return or enter to open this section' ); ?></span>
 363                         </h3>
 364                         <ul class="accordion-section-content">
 365                                 <li class="customize-section-description-container section-meta <# if ( data.description_hidden ) { #>customize-info<# } #>">
 366                                         <div class="customize-section-title">
 367                                                 <button class="customize-section-back" tabindex="-1">
 368                                                         <span class="screen-reader-text"><?php _e( 'Back' ); ?></span>
 369                                                 </button>
 370                                                 <h3>
 371                                                         <span class="customize-action">
 372                                                                 {{{ data.customizeAction }}}
 373                                                         </span>
 374                                                         {{ data.title }}
 375                                                 </h3>
 376                                                 <# if ( data.description && data.description_hidden ) { #>
 377                                                         <button type="button" class="customize-help-toggle dashicons dashicons-editor-help" aria-expanded="false"><span class="screen-reader-text"><?php _e( 'Help' ); ?></span></button>
 378                                                         <div class="description customize-section-description">
 379                                                                 {{{ data.description }}}
 380                                                         </div>
 381                                                 <# } #>
 382                                         </div>
 383
 384                                         <# if ( data.description && ! data.description_hidden ) { #>
 385                                                 <div class="description customize-section-description">
 386                                                         {{{ data.description }}}
 387                                                 </div>
 388                                         <# } #>
 389                                 </li>
 390                         </ul>
 391                 </li>
 392                 <?php
 393         }
 394 }
 395
 396 /** WP_Customize_Themes_Section class */
 397 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-themes-section.php' );
 398
 399 /** WP_Customize_Sidebar_Section class */
 400 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-sidebar-section.php' );
 401
 402 /** WP_Customize_Nav_Menu_Section class */
 403 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-section.php' );
 404
 405 /** WP_Customize_New_Menu_Section class */
 406 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-new-menu-section.php' );