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