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          *
  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 4.0.0
  47          * @access public
  48          * @var WP_Customize_Manager
  49          */
  50         public $manager;
  51
  52         /**
  53          * Unique identifier.
  54          *
  55          * @since 4.0.0
  56          * @access public
  57          * @var string
  58          */
  59         public $id;
  60
  61         /**
  62          * Priority of the panel, defining the display order of panels and sections.
  63          *
  64          * @since 4.0.0
  65          * @access public
  66          * @var integer
  67          */
  68         public $priority = 160;
  69
  70         /**
  71          * Capability required for the panel.
  72          *
  73          * @since 4.0.0
  74          * @access public
  75          * @var string
  76          */
  77         public $capability = 'edit_theme_options';
  78
  79         /**
  80          * Theme feature support for the panel.
  81          *
  82          * @since 4.0.0
  83          * @access public
  84          * @var string|array
  85          */
  86         public $theme_supports = '';
  87
  88         /**
  89          * Title of the panel to show in UI.
  90          *
  91          * @since 4.0.0
  92          * @access public
  93          * @var string
  94          */
  95         public $title = '';
  96
  97         /**
  98          * Description to show in the UI.
  99          *
 100          * @since 4.0.0
 101          * @access public
 102          * @var string
 103          */
 104         public $description = '';
 105
 106         /**
 107          * Customizer sections for this panel.
 108          *
 109          * @since 4.0.0
 110          * @access public
 111          * @var array
 112          */
 113         public $sections;
 114
 115         /**
 116          * Type of this panel.
 117          *
 118          * @since 4.1.0
 119          * @access public
 120          * @var string
 121          */
 122         public $type = 'default';
 123
 124         /**
 125          * Active callback.
 126          *
 127          * @since 4.1.0
 128          * @access public
 129          *
 130          * @see WP_Customize_Section::active()
 131          *
 132          * @var callable Callback is called with one argument, the instance of
 133          *               {@see WP_Customize_Section}, and returns bool to indicate
 134          *               whether the section is active (such as it relates to the URL
 135          *               currently being previewed).
 136          */
 137         public $active_callback = '';
 138
 139         /**
 140          * Constructor.
 141          *
 142          * Any supplied $args override class property defaults.
 143          *
 144          * @since 4.0.0
 145          *
 146          * @param WP_Customize_Manager $manager Customizer bootstrap instance.
 147          * @param string               $id      An specific ID for the panel.
 148          * @param array                $args    Panel arguments.
 149          */
 150         public function __construct( $manager, $id, $args = array() ) {
 151                 $keys = array_keys( get_object_vars( $this ) );
 152                 foreach ( $keys as $key ) {
 153                         if ( isset( $args[ $key ] ) ) {
 154                                 $this->$key = $args[ $key ];
 155                         }
 156                 }
 157
 158                 $this->manager = $manager;
 159                 $this->id = $id;
 160                 if ( empty( $this->active_callback ) ) {
 161                         $this->active_callback = array( $this, 'active_callback' );
 162                 }
 163                 self::$instance_count += 1;
 164                 $this->instance_number = self::$instance_count;
 165
 166                 $this->sections = array(); // Users cannot customize the $sections array.
 167         }
 168
 169         /**
 170          * Check whether panel is active to current Customizer preview.
 171          *
 172          * @since 4.1.0
 173          * @access public
 174          *
 175          * @return bool Whether the panel is active to the current preview.
 176          */
 177         final public function active() {
 178                 $panel = $this;
 179                 $active = call_user_func( $this->active_callback, $this );
 180
 181                 /**
 182                  * Filter response of WP_Customize_Panel::active().
 183                  *
 184                  * @since 4.1.0
 185                  *
 186                  * @param bool               $active  Whether the Customizer panel is active.
 187                  * @param WP_Customize_Panel $panel   {@see WP_Customize_Panel} instance.
 188                  */
 189                 $active = apply_filters( 'customize_panel_active', $active, $panel );
 190
 191                 return $active;
 192         }
 193
 194         /**
 195          * Default callback used when invoking {@see WP_Customize_Panel::active()}.
 196          *
 197          * Subclasses can override this with their specific logic, or they may
 198          * provide an 'active_callback' argument to the constructor.
 199          *
 200          * @since 4.1.0
 201          * @access public
 202          *
 203          * @return bool Always true.
 204          */
 205         public function active_callback() {
 206                 return true;
 207         }
 208
 209         /**
 210          * Gather the parameters passed to client JavaScript via JSON.
 211          *
 212          * @since 4.1.0
 213          *
 214          * @return array The array to be exported to the client as JSON.
 215          */
 216         public function json() {
 217                 $array = wp_array_slice_assoc( (array) $this, array( 'id', 'description', 'priority', 'type' ) );
 218                 $array['title'] = html_entity_decode( $this->title, ENT_QUOTES, get_bloginfo( 'charset' ) );
 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 panel.
 228          *
 229          * @since 4.0.0
 230          *
 231          * @return bool False if theme doesn't support the panel or the user doesn't have the capability.
 232          */
 233         final public 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 panel's content template for insertion into the Customizer pane.
 247          *
 248          * @since 4.1.0
 249          *
 250          * @return string Content for the panel.
 251          */
 252         final public function get_content() {
 253                 ob_start();
 254                 $this->maybe_render();
 255                 return trim( ob_get_clean() );
 256         }
 257
 258         /**
 259          * Check capabilities and render the panel.
 260          *
 261          * @since 4.0.0
 262          */
 263         final public function maybe_render() {
 264                 if ( ! $this->check_capabilities() ) {
 265                         return;
 266                 }
 267
 268                 /**
 269                  * Fires before rendering a Customizer panel.
 270                  *
 271                  * @since 4.0.0
 272                  *
 273                  * @param WP_Customize_Panel $this WP_Customize_Panel instance.
 274                  */
 275                 do_action( 'customize_render_panel', $this );
 276
 277                 /**
 278                  * Fires before rendering a specific Customizer panel.
 279                  *
 280                  * The dynamic portion of the hook name, `$this->id`, refers to
 281                  * the ID of the specific Customizer panel to be rendered.
 282                  *
 283                  * @since 4.0.0
 284                  */
 285                 do_action( "customize_render_panel_{$this->id}" );
 286
 287                 $this->render();
 288         }
 289
 290         /**
 291          * Render the panel container, and then its contents (via `this->render_content()`) in a subclass.
 292          *
 293          * Panel containers are now rendered in JS by default, see {@see WP_Customize_Panel::print_template()}.
 294          *
 295          * @since 4.0.0
 296          * @access protected
 297          */
 298         protected function render() {}
 299
 300         /**
 301          * Render the panel UI in a subclass.
 302          *
 303          * Panel contents are now rendered in JS by default, see {@see WP_Customize_Panel::print_template()}.
 304          *
 305          * @since 4.1.0
 306          * @access protected
 307          */
 308         protected function render_content() {}
 309
 310         /**
 311          * Render the panel's JS templates.
 312          *
 313          * This function is only run for panel types that have been registered with
 314          * WP_Customize_Manager::register_panel_type().
 315          *
 316          * @since 4.3.0
 317          *
 318          * @see WP_Customize_Manager::register_panel_type()
 319          */
 320         public function print_template() {
 321                 ?>
 322                 <script type="text/html" id="tmpl-customize-panel-<?php echo esc_attr( $this->type ); ?>-content">
 323                         <?php $this->content_template(); ?>
 324                 </script>
 325                 <script type="text/html" id="tmpl-customize-panel-<?php echo esc_attr( $this->type ); ?>">
 326                         <?php $this->render_template(); ?>
 327                 </script>
 328         <?php
 329         }
 330
 331         /**
 332          * An Underscore (JS) template for rendering this panel's container.
 333          *
 334          * Class variables for this panel class are available in the `data` JS object;
 335          * export custom variables by overriding WP_Customize_Panel::json().
 336          *
 337          * @see WP_Customize_Panel::print_template()
 338          *
 339          * @since 4.3.0
 340          * @access protected
 341          */
 342         protected function render_template() {
 343                 ?>
 344                 <li id="accordion-panel-{{ data.id }}" class="accordion-section control-section control-panel control-panel-{{ data.type }}">
 345                         <h3 class="accordion-section-title" tabindex="0">
 346                                 {{ data.title }}
 347                                 <span class="screen-reader-text"><?php _e( 'Press return or enter to open this panel' ); ?></span>
 348                         </h3>
 349                         <ul class="accordion-sub-container control-panel-content"></ul>
 350                 </li>
 351                 <?php
 352         }
 353
 354         /**
 355          * An Underscore (JS) template for this panel's content (but not its container).
 356          *
 357          * Class variables for this panel class are available in the `data` JS object;
 358          * export custom variables by overriding WP_Customize_Panel::json().
 359          *
 360          * @see WP_Customize_Panel::print_template()
 361          *
 362          * @since 4.3.0
 363          * @access protected
 364          */
 365         protected function content_template() {
 366                 ?>
 367                 <li class="panel-meta customize-info accordion-section <# if ( ! data.description ) { #> cannot-expand<# } #>">
 368                         <button class="customize-panel-back" tabindex="-1"><span class="screen-reader-text"><?php _e( 'Back' ); ?></span></button>
 369                         <div class="accordion-section-title">
 370                                 <span class="preview-notice"><?php
 371                                         /* translators: %s: the site/panel title in the Customizer */
 372                                         echo sprintf( __( 'You are customizing %s' ), '<strong class="panel-title">{{ data.title }}</strong>' );
 373                                 ?></span>
 374                                 <# if ( data.description ) { #>
 375                                         <button class="customize-help-toggle dashicons dashicons-editor-help" tabindex="0" aria-expanded="false"><span class="screen-reader-text"><?php _e( 'Help' ); ?></span></button>
 376                                 <# } #>
 377                         </div>
 378                         <# if ( data.description ) { #>
 379                                 <div class="description customize-panel-description">
 380                                         {{{ data.description }}}
 381                                 </div>
 382                         <# } #>
 383                 </li>
 384                 <?php
 385         }
 386 }
 387
 388 /** WP_Customize_Nav_Menus_Panel class */
 389 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menus-panel.php' );