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