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

   1 <?php
   2 /**
   3  * Customize Panel Class.
   4  *
   5  * A UI container for sections, managed by the WP_Customize_Manager.
   6  *
   7  * @package WordPress
   8  * @subpackage Customize
   9  * @since 4.0.0
  10  */
  11 class WP_Customize_Panel {
  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 4.0.0
  37          * @access public
  38          * @var WP_Customize_Manager
  39          */
  40         public $manager;
  41
  42         /**
  43          * Unique identifier.
  44          *
  45          * @since 4.0.0
  46          * @access public
  47          * @var string
  48          */
  49         public $id;
  50
  51         /**
  52          * Priority of the panel, defining the display order of panels and sections.
  53          *
  54          * @since 4.0.0
  55          * @access public
  56          * @var integer
  57          */
  58         public $priority = 160;
  59
  60         /**
  61          * Capability required for the panel.
  62          *
  63          * @since 4.0.0
  64          * @access public
  65          * @var string
  66          */
  67         public $capability = 'edit_theme_options';
  68
  69         /**
  70          * Theme feature support for the panel.
  71          *
  72          * @since 4.0.0
  73          * @access public
  74          * @var string|array
  75          */
  76         public $theme_supports = '';
  77
  78         /**
  79          * Title of the panel to show in UI.
  80          *
  81          * @since 4.0.0
  82          * @access public
  83          * @var string
  84          */
  85         public $title = '';
  86
  87         /**
  88          * Description to show in the UI.
  89          *
  90          * @since 4.0.0
  91          * @access public
  92          * @var string
  93          */
  94         public $description = '';
  95
  96         /**
  97          * Customizer sections for this panel.
  98          *
  99          * @since 4.0.0
 100          * @access public
 101          * @var array
 102          */
 103         public $sections;
 104
 105         /**
 106          * Type of this panel.
 107          *
 108          * @since 4.1.0
 109          * @access public
 110          * @var string
 111          */
 112         public $type = 'default';
 113
 114         /**
 115          * Active callback.
 116          *
 117          * @since 4.1.0
 118          * @access public
 119          *
 120          * @see WP_Customize_Section::active()
 121          *
 122          * @var callable Callback is called with one argument, the instance of
 123          *               {@see WP_Customize_Section}, and returns bool to indicate
 124          *               whether the section is active (such as it relates to the URL
 125          *               currently being previewed).
 126          */
 127         public $active_callback = '';
 128
 129         /**
 130          * Constructor.
 131          *
 132          * Any supplied $args override class property defaults.
 133          *
 134          * @since 4.0.0
 135          *
 136          * @param WP_Customize_Manager $manager Customizer bootstrap instance.
 137          * @param string               $id      An specific ID for the panel.
 138          * @param array                $args    Panel arguments.
 139          */
 140         public function __construct( $manager, $id, $args = array() ) {
 141                 $keys = array_keys( get_object_vars( $this ) );
 142                 foreach ( $keys as $key ) {
 143                         if ( isset( $args[ $key ] ) ) {
 144                                 $this->$key = $args[ $key ];
 145                         }
 146                 }
 147
 148                 $this->manager = $manager;
 149                 $this->id = $id;
 150                 if ( empty( $this->active_callback ) ) {
 151                         $this->active_callback = array( $this, 'active_callback' );
 152                 }
 153                 self::$instance_count += 1;
 154                 $this->instance_number = self::$instance_count;
 155
 156                 $this->sections = array(); // Users cannot customize the $sections array.
 157
 158                 return $this;
 159         }
 160
 161         /**
 162          * Check whether panel is active to current Customizer preview.
 163          *
 164          * @since 4.1.0
 165          * @access public
 166          *
 167          * @return bool Whether the panel is active to the current preview.
 168          */
 169         public final function active() {
 170                 $panel = $this;
 171                 $active = call_user_func( $this->active_callback, $this );
 172
 173                 /**
 174                  * Filter response of WP_Customize_Panel::active().
 175                  *
 176                  * @since 4.1.0
 177                  *
 178                  * @param bool               $active  Whether the Customizer panel is active.
 179                  * @param WP_Customize_Panel $panel   {@see WP_Customize_Panel} instance.
 180                  */
 181                 $active = apply_filters( 'customize_panel_active', $active, $panel );
 182
 183                 return $active;
 184         }
 185
 186         /**
 187          * Default callback used when invoking {@see WP_Customize_Panel::active()}.
 188          *
 189          * Subclasses can override this with their specific logic, or they may
 190          * provide an 'active_callback' argument to the constructor.
 191          *
 192          * @since 4.1.0
 193          * @access public
 194          *
 195          * @return bool Always true.
 196          */
 197         public function active_callback() {
 198                 return true;
 199         }
 200
 201         /**
 202          * Gather the parameters passed to client JavaScript via JSON.
 203          *
 204          * @since 4.1.0
 205          *
 206          * @return array The array to be exported to the client as JSON.
 207          */
 208         public function json() {
 209                 $array = wp_array_slice_assoc( (array) $this, array( 'title', 'description', 'priority', 'type' ) );
 210                 $array['content'] = $this->get_content();
 211                 $array['active'] = $this->active();
 212                 $array['instanceNumber'] = $this->instance_number;
 213                 return $array;
 214         }
 215
 216         /**
 217          * Checks required user capabilities and whether the theme has the
 218          * feature support required by the panel.
 219          *
 220          * @since 4.0.0
 221          *
 222          * @return bool False if theme doesn't support the panel or the user doesn't have the capability.
 223          */
 224         public final function check_capabilities() {
 225                 if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) ) {
 226                         return false;
 227                 }
 228
 229                 if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) ) {
 230                         return false;
 231                 }
 232
 233                 return true;
 234         }
 235
 236         /**
 237          * Get the panel's content template for insertion into the Customizer pane.
 238          *
 239          * @since 4.1.0
 240          *
 241          * @return string Content for the panel.
 242          */
 243         public final function get_content() {
 244                 ob_start();
 245                 $this->maybe_render();
 246                 $template = trim( ob_get_contents() );
 247                 ob_end_clean();
 248                 return $template;
 249         }
 250
 251         /**
 252          * Check capabilities and render the panel.
 253          *
 254          * @since 4.0.0
 255          */
 256         public final function maybe_render() {
 257                 if ( ! $this->check_capabilities() ) {
 258                         return;
 259                 }
 260
 261                 /**
 262                  * Fires before rendering a Customizer panel.
 263                  *
 264                  * @since 4.0.0
 265                  *
 266                  * @param WP_Customize_Panel $this WP_Customize_Panel instance.
 267                  */
 268                 do_action( 'customize_render_panel', $this );
 269
 270                 /**
 271                  * Fires before rendering a specific Customizer panel.
 272                  *
 273                  * The dynamic portion of the hook name, `$this->id`, refers to
 274                  * the ID of the specific Customizer panel to be rendered.
 275                  *
 276                  * @since 4.0.0
 277                  */
 278                 do_action( "customize_render_panel_{$this->id}" );
 279
 280                 $this->render();
 281         }
 282
 283         /**
 284          * Render the panel container, and then its contents.
 285          *
 286          * @since 4.0.0
 287          * @access protected
 288          */
 289         protected function render() {
 290                 $classes = 'accordion-section control-section control-panel control-panel-' . $this->type;
 291                 ?>
 292                 <li id="accordion-panel-<?php echo esc_attr( $this->id ); ?>" class="<?php echo esc_attr( $classes ); ?>">
 293                         <h3 class="accordion-section-title" tabindex="0">
 294                                 <?php echo esc_html( $this->title ); ?>
 295                                 <span class="screen-reader-text"><?php _e( 'Press return or enter to open this panel' ); ?></span>
 296                         </h3>
 297                         <ul class="accordion-sub-container control-panel-content">
 298                                 <?php $this->render_content(); ?>
 299                         </ul>
 300                 </li>
 301                 <?php
 302         }
 303
 304         /**
 305          * Render the sections that have been added to the panel.
 306          *
 307          * @since 4.1.0
 308          * @access protected
 309          */
 310         protected function render_content() {
 311                 ?>
 312                 <li class="panel-meta accordion-section control-section<?php if ( empty( $this->description ) ) { echo ' cannot-expand'; } ?>">
 313                         <div class="accordion-section-title" tabindex="0">
 314                                 <span class="preview-notice"><?php
 315                                         /* translators: %s is the site/panel title in the Customizer */
 316                                         echo sprintf( __( 'You are customizing %s' ), '<strong class="panel-title">' . esc_html( $this->title ) . '</strong>' );
 317                                 ?></span>
 318                         </div>
 319                         <?php if ( ! empty( $this->description ) ) : ?>
 320                                 <div class="accordion-section-content description">
 321                                         <?php echo $this->description; ?>
 322                                 </div>
 323                         <?php endif; ?>
 324                 </li>
 325                 <?php
 326         }
 327 }