[Summary view] [Print] [Text view]

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