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