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

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