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          * @access protected
  28          * @var int
  29          */
  30         protected static $instance_count = 0;
  31
  32         /**
  33          * Order in which this instance was created in relation to other instances.
  34          *
  35          * @since 4.1.0
  36          * @access public
  37          * @var int
  38          */
  39         public $instance_number;
  40
  41         /**
  42          * WP_Customize_Manager instance.
  43          *
  44          * @since 3.4.0
  45          * @access public
  46          * @var WP_Customize_Manager
  47          */
  48         public $manager;
  49
  50         /**
  51          * Unique identifier.
  52          *
  53          * @since 3.4.0
  54          * @access public
  55          * @var string
  56          */
  57         public $id;
  58
  59         /**
  60          * Priority of the section which informs load order of sections.
  61          *
  62          * @since 3.4.0
  63          * @access public
  64          * @var integer
  65          */
  66         public $priority = 160;
  67
  68         /**
  69          * Panel in which to show the section, making it a sub-section.
  70          *
  71          * @since 4.0.0
  72          * @access public
  73          * @var string
  74          */
  75         public $panel = '';
  76
  77         /**
  78          * Capability required for the section.
  79          *
  80          * @since 3.4.0
  81          * @access public
  82          * @var string
  83          */
  84         public $capability = 'edit_theme_options';
  85
  86         /**
  87          * Theme feature support for the section.
  88          *
  89          * @since 3.4.0
  90          * @access public
  91          * @var string|array
  92          */
  93         public $theme_supports = '';
  94
  95         /**
  96          * Title of the section to show in UI.
  97          *
  98          * @since 3.4.0
  99          * @access public
 100          * @var string
 101          */
 102         public $title = '';
 103
 104         /**
 105          * Description to show in the UI.
 106          *
 107          * @since 3.4.0
 108          * @access public
 109          * @var string
 110          */
 111         public $description = '';
 112
 113         /**
 114          * Customizer controls for this section.
 115          *
 116          * @since 3.4.0
 117          * @access public
 118          * @var array
 119          */
 120         public $controls;
 121
 122         /**
 123          * Type of this section.
 124          *
 125          * @since 4.1.0
 126          * @access public
 127          * @var string
 128          */
 129         public $type = 'default';
 130
 131         /**
 132          * Active callback.
 133          *
 134          * @since 4.1.0
 135          * @access public
 136          *
 137          * @see WP_Customize_Section::active()
 138          *
 139          * @var callable Callback is called with one argument, the instance of
 140          *               {@see WP_Customize_Section}, and returns bool to indicate
 141          *               whether the section is active (such as it relates to the URL
 142          *               currently being previewed).
 143          */
 144         public $active_callback = '';
 145
 146         /**
 147          * Constructor.
 148          *
 149          * Any supplied $args override class property defaults.
 150          *
 151          * @since 3.4.0
 152          *
 153          * @param WP_Customize_Manager $manager Customizer bootstrap instance.
 154          * @param string               $id      An specific ID of the section.
 155          * @param array                $args    Section arguments.
 156          */
 157         public function __construct( $manager, $id, $args = array() ) {
 158                 $keys = array_keys( get_object_vars( $this ) );
 159                 foreach ( $keys as $key ) {
 160                         if ( isset( $args[ $key ] ) ) {
 161                                 $this->$key = $args[ $key ];
 162                         }
 163                 }
 164
 165                 $this->manager = $manager;
 166                 $this->id = $id;
 167                 if ( empty( $this->active_callback ) ) {
 168                         $this->active_callback = array( $this, 'active_callback' );
 169                 }
 170                 self::$instance_count += 1;
 171                 $this->instance_number = self::$instance_count;
 172
 173                 $this->controls = array(); // Users cannot customize the $controls array.
 174         }
 175
 176         /**
 177          * Check whether section is active to current Customizer preview.
 178          *
 179          * @since 4.1.0
 180          * @access public
 181          *
 182          * @return bool Whether the section is active to the current preview.
 183          */
 184         final public function active() {
 185                 $section = $this;
 186                 $active = call_user_func( $this->active_callback, $this );
 187
 188                 /**
 189                  * Filter response of {@see WP_Customize_Section::active()}.
 190                  *
 191                  * @since 4.1.0
 192                  *
 193                  * @param bool                 $active  Whether the Customizer section is active.
 194                  * @param WP_Customize_Section $section {@see WP_Customize_Section} instance.
 195                  */
 196                 $active = apply_filters( 'customize_section_active', $active, $section );
 197
 198                 return $active;
 199         }
 200
 201         /**
 202          * Default callback used when invoking {@see WP_Customize_Section::active()}.
 203          *
 204          * Subclasses can override this with their specific logic, or they may provide
 205          * an 'active_callback' argument to the constructor.
 206          *
 207          * @since 4.1.0
 208          * @access public
 209          *
 210          * @return bool Always true.
 211          */
 212         public function active_callback() {
 213                 return true;
 214         }
 215
 216         /**
 217          * Gather the parameters passed to client JavaScript via JSON.
 218          *
 219          * @since 4.1.0
 220          *
 221          * @return array The array to be exported to the client as JSON.
 222          */
 223         public function json() {
 224                 $array = wp_array_slice_assoc( (array) $this, array( 'title', 'description', 'priority', 'panel', 'type' ) );
 225                 $array['content'] = $this->get_content();
 226                 $array['active'] = $this->active();
 227                 $array['instanceNumber'] = $this->instance_number;
 228                 return $array;
 229         }
 230
 231         /**
 232          * Checks required user capabilities and whether the theme has the
 233          * feature support required by the section.
 234          *
 235          * @since 3.4.0
 236          *
 237          * @return bool False if theme doesn't support the section or user doesn't have the capability.
 238          */
 239         final public function check_capabilities() {
 240                 if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) ) {
 241                         return false;
 242                 }
 243
 244                 if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) ) {
 245                         return false;
 246                 }
 247
 248                 return true;
 249         }
 250
 251         /**
 252          * Get the section's content template for insertion into the Customizer pane.
 253          *
 254          * @since 4.1.0
 255          *
 256          * @return string Contents of the section.
 257          */
 258         final public function get_content() {
 259                 ob_start();
 260                 $this->maybe_render();
 261                 $template = trim( ob_get_contents() );
 262                 ob_end_clean();
 263                 return $template;
 264         }
 265
 266         /**
 267          * Check capabilities and render the section.
 268          *
 269          * @since 3.4.0
 270          */
 271         final public function maybe_render() {
 272                 if ( ! $this->check_capabilities() ) {
 273                         return;
 274                 }
 275
 276                 /**
 277                  * Fires before rendering a Customizer section.
 278                  *
 279                  * @since 3.4.0
 280                  *
 281                  * @param WP_Customize_Section $this WP_Customize_Section instance.
 282                  */
 283                 do_action( 'customize_render_section', $this );
 284                 /**
 285                  * Fires before rendering a specific Customizer section.
 286                  *
 287                  * The dynamic portion of the hook name, `$this->id`, refers to the ID
 288                  * of the specific Customizer section to be rendered.
 289                  *
 290                  * @since 3.4.0
 291                  */
 292                 do_action( "customize_render_section_{$this->id}" );
 293
 294                 $this->render();
 295         }
 296
 297         /**
 298          * Render the section, and the controls that have been added to it.
 299          *
 300          * @since 3.4.0
 301          */
 302         protected function render() {
 303                 $classes = 'accordion-section control-section control-section-' . $this->type;
 304                 ?>
 305                 <li id="accordion-section-<?php echo esc_attr( $this->id ); ?>" class="<?php echo esc_attr( $classes ); ?>">
 306                         <h3 class="accordion-section-title" tabindex="0">
 307                                 <?php echo esc_html( $this->title ); ?>
 308                                 <span class="screen-reader-text"><?php _e( 'Press return or enter to expand' ); ?></span>
 309                         </h3>
 310                         <ul class="accordion-section-content">
 311                                 <?php if ( ! empty( $this->description ) ) : ?>
 312                                         <li class="customize-section-description-container">
 313                                                 <p class="description customize-section-description"><?php echo $this->description; ?></p>
 314                                         </li>
 315                                 <?php endif; ?>
 316                         </ul>
 317                 </li>
 318                 <?php
 319         }
 320 }
 321
 322 /**
 323  * Customize Themes Section class.
 324  *
 325  * A UI container for theme controls, which behaves like a backwards Panel.
 326  *
 327  * @since 4.2.0
 328  *
 329  * @see WP_Customize_Section
 330  */
 331 class WP_Customize_Themes_Section extends WP_Customize_Section {
 332
 333         /**
 334          * Customize section type.
 335          *
 336          * @since 4.2.0
 337          * @access public
 338          * @var string
 339          */
 340         public $type = 'themes';
 341
 342         /**
 343          * Render the themes section, which behaves like a panel.
 344          *
 345          * @since 4.2.0
 346          * @access protected
 347          */
 348         protected function render() {
 349                 $classes = 'accordion-section control-section control-section-' . $this->type;
 350                 ?>
 351                 <li id="accordion-section-<?php echo esc_attr( $this->id ); ?>" class="<?php echo esc_attr( $classes ); ?>">
 352                         <h3 class="accordion-section-title">
 353                                 <?php
 354                                 if ( $this->manager->is_theme_active() ) {
 355                                         /* translators: %s: theme name */
 356                                         printf( __( '<span>Active theme</span> %s' ), $this->title );
 357                                 } else {
 358                                         /* translators: %s: theme name */
 359                                         printf( __( '<span>Previewing theme</span> %s' ), $this->title );
 360                                 }
 361                                 ?>
 362
 363                                 <button type="button" class="button change-theme"><?php _ex( 'Change', 'theme' ); ?></button>
 364                         </h3>
 365                         <div class="customize-themes-panel control-panel-content themes-php">
 366                                 <h2>
 367                                         <?php _e( 'Themes' ); ?>
 368                                         <span class="title-count theme-count"><?php echo count( $this->controls ) + 1 /* Active theme */; ?></span>
 369                                 </h2>
 370
 371                                 <h3 class="accordion-section-title customize-section-title">
 372                                         <?php
 373                                         if ( $this->manager->is_theme_active() ) {
 374                                                 /* translators: %s: theme name */
 375                                                 printf( __( '<span>Active theme</span> %s' ), $this->title );
 376                                         } else {
 377                                                 /* translators: %s: theme name */
 378                                                 printf( __( '<span>Previewing theme</span> %s' ), $this->title );
 379                                         }
 380                                         ?>
 381                                         <button type="button" class="button customize-theme"><?php _e( 'Customize' ); ?></button>
 382                                 </h3>
 383
 384                                 <div class="theme-overlay" tabindex="0" role="dialog" aria-label="<?php esc_attr_e( 'Theme Details' ); ?>"></div>
 385
 386                                 <div id="customize-container"></div>
 387                                 <?php if ( count( $this->controls ) > 4 ) : ?>
 388                                         <p><label for="themes-filter">
 389                                                 <span class="screen-reader-text"><?php _e( 'Search installed themes...' ); ?></span>
 390                                                 <input type="text" id="themes-filter" placeholder="<?php esc_attr_e( 'Search installed themes...' ); ?>" />
 391                                         </label></p>
 392                                 <?php endif; ?>
 393                                 <div class="theme-browser rendered">
 394                                         <ul class="themes accordion-section-content">
 395                                         </ul>
 396                                 </div>
 397                         </div>
 398                 </li>
 399 <?php }
 400 }
 401
 402 /**
 403  * Customizer section representing widget area (sidebar).
 404  *
 405  * @since 4.1.0
 406  *
 407  * @see WP_Customize_Section
 408  */
 409 class WP_Customize_Sidebar_Section extends WP_Customize_Section {
 410
 411         /**
 412          * Type of this section.
 413          *
 414          * @since 4.1.0
 415          * @access public
 416          * @var string
 417          */
 418         public $type = 'sidebar';
 419
 420         /**
 421          * Unique identifier.
 422          *
 423          * @since 4.1.0
 424          * @access public
 425          * @var string
 426          */
 427         public $sidebar_id;
 428
 429         /**
 430          * Gather the parameters passed to client JavaScript via JSON.
 431          *
 432          * @since 4.1.0
 433          *
 434          * @return array The array to be exported to the client as JSON.
 435          */
 436         public function json() {
 437                 $json = parent::json();
 438                 $json['sidebarId'] = $this->sidebar_id;
 439                 return $json;
 440         }
 441
 442         /**
 443          * Whether the current sidebar is rendered on the page.
 444          *
 445          * @since 4.1.0
 446          * @access public
 447          *
 448          * @return bool Whether sidebar is rendered.
 449          */
 450         public function active_callback() {
 451                 return $this->manager->widgets->is_sidebar_rendered( $this->sidebar_id );
 452         }
 453 }