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

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