home *** CD-ROM | disk | FTP | other *** search
/ HTML Examples / WP.iso / wordpress / wp-includes / class-wp-customize-section.php < prev    next >
Encoding:
PHP Script  |  2017-10-27  |  10.0 KB  |  399 lines
  1. <?php
  2. /**
  3.  * WordPress Customize Section classes
  4.  *
  5.  * @package WordPress
  6.  * @subpackage Customize
  7.  * @since 3.4.0
  8.  */
  9.  
  10. /**
  11.  * Customize Section class.
  12.  *
  13.  * A UI container for controls, managed by the WP_Customize_Manager class.
  14.  *
  15.  * @since 3.4.0
  16.  *
  17.  * @see WP_Customize_Manager
  18.  */
  19. class WP_Customize_Section {
  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 3.4.0
  45.      * @var WP_Customize_Manager
  46.      */
  47.     public $manager;
  48.  
  49.     /**
  50.      * Unique identifier.
  51.      *
  52.      * @since 3.4.0
  53.      * @var string
  54.      */
  55.     public $id;
  56.  
  57.     /**
  58.      * Priority of the section which informs load order of sections.
  59.      *
  60.      * @since 3.4.0
  61.      * @var integer
  62.      */
  63.     public $priority = 160;
  64.  
  65.     /**
  66.      * Panel in which to show the section, making it a sub-section.
  67.      *
  68.      * @since 4.0.0
  69.      * @var string
  70.      */
  71.     public $panel = '';
  72.  
  73.     /**
  74.      * Capability required for the section.
  75.      *
  76.      * @since 3.4.0
  77.      * @var string
  78.      */
  79.     public $capability = 'edit_theme_options';
  80.  
  81.     /**
  82.      * Theme feature support for the section.
  83.      *
  84.      * @since 3.4.0
  85.      * @var string|array
  86.      */
  87.     public $theme_supports = '';
  88.  
  89.     /**
  90.      * Title of the section to show in UI.
  91.      *
  92.      * @since 3.4.0
  93.      * @var string
  94.      */
  95.     public $title = '';
  96.  
  97.     /**
  98.      * Description to show in the UI.
  99.      *
  100.      * @since 3.4.0
  101.      * @var string
  102.      */
  103.     public $description = '';
  104.  
  105.     /**
  106.      * Customizer controls for this section.
  107.      *
  108.      * @since 3.4.0
  109.      * @var array
  110.      */
  111.     public $controls;
  112.  
  113.     /**
  114.      * Type of this section.
  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.      * Show the description or hide it behind the help icon.
  137.      *
  138.      * @since 4.7.0
  139.      *
  140.      * @var bool Indicates whether the Section's description should be
  141.      *           hidden behind a help icon ("?") in the Section header,
  142.      *           similar to how help icons are displayed on Panels.
  143.      */
  144.     public $description_hidden = false;
  145.  
  146.     /**
  147.      * Constructor.
  148.      *
  149.      * Any supplied $args override class property defaults.
  150.      *
  151.      * @since 3.4.0
  152.      *
  153.      * @param WP_Customize_Manager $manager Customizer bootstrap instance.
  154.      * @param string               $id      An specific ID of the section.
  155.      * @param array                $args    Section arguments.
  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->controls = array(); // Users cannot customize the $controls array.
  174.     }
  175.  
  176.     /**
  177.      * Check whether section is active to current Customizer preview.
  178.      *
  179.      * @since 4.1.0
  180.      *
  181.      * @return bool Whether the section is active to the current preview.
  182.      */
  183.     final public function active() {
  184.         $section = $this;
  185.         $active = call_user_func( $this->active_callback, $this );
  186.  
  187.         /**
  188.          * Filters response of WP_Customize_Section::active().
  189.          *
  190.          * @since 4.1.0
  191.          *
  192.          * @param bool                 $active  Whether the Customizer section is active.
  193.          * @param WP_Customize_Section $section WP_Customize_Section instance.
  194.          */
  195.         $active = apply_filters( 'customize_section_active', $active, $section );
  196.  
  197.         return $active;
  198.     }
  199.  
  200.     /**
  201.      * Default callback used when invoking WP_Customize_Section::active().
  202.      *
  203.      * Subclasses can override this with their specific logic, or they may provide
  204.      * an 'active_callback' argument to the constructor.
  205.      *
  206.      * @since 4.1.0
  207.      *
  208.      * @return true 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', 'panel', 'type', 'description_hidden' ) );
  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.  
  228.         if ( $this->panel ) {
  229.             /* translators: ▸ is the unicode right-pointing triangle, and %s is the section title in the Customizer */
  230.             $array['customizeAction'] = sprintf( __( 'Customizing ▸ %s' ), esc_html( $this->manager->get_panel( $this->panel )->title ) );
  231.         } else {
  232.             $array['customizeAction'] = __( 'Customizing' );
  233.         }
  234.  
  235.         return $array;
  236.     }
  237.  
  238.     /**
  239.      * Checks required user capabilities and whether the theme has the
  240.      * feature support required by the section.
  241.      *
  242.      * @since 3.4.0
  243.      *
  244.      * @return bool False if theme doesn't support the section or user doesn't have the capability.
  245.      */
  246.     final public function check_capabilities() {
  247.         if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) ) {
  248.             return false;
  249.         }
  250.  
  251.         if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) ) {
  252.             return false;
  253.         }
  254.  
  255.         return true;
  256.     }
  257.  
  258.     /**
  259.      * Get the section's content for insertion into the Customizer pane.
  260.      *
  261.      * @since 4.1.0
  262.      *
  263.      * @return string Contents of the section.
  264.      */
  265.     final public function get_content() {
  266.         ob_start();
  267.         $this->maybe_render();
  268.         return trim( ob_get_clean() );
  269.     }
  270.  
  271.     /**
  272.      * Check capabilities and render the section.
  273.      *
  274.      * @since 3.4.0
  275.      */
  276.     final public function maybe_render() {
  277.         if ( ! $this->check_capabilities() ) {
  278.             return;
  279.         }
  280.  
  281.         /**
  282.          * Fires before rendering a Customizer section.
  283.          *
  284.          * @since 3.4.0
  285.          *
  286.          * @param WP_Customize_Section $this WP_Customize_Section instance.
  287.          */
  288.         do_action( 'customize_render_section', $this );
  289.         /**
  290.          * Fires before rendering a specific Customizer section.
  291.          *
  292.          * The dynamic portion of the hook name, `$this->id`, refers to the ID
  293.          * of the specific Customizer section to be rendered.
  294.          *
  295.          * @since 3.4.0
  296.          */
  297.         do_action( "customize_render_section_{$this->id}" );
  298.  
  299.         $this->render();
  300.     }
  301.  
  302.     /**
  303.      * Render the section UI in a subclass.
  304.      *
  305.      * Sections are now rendered in JS by default, see WP_Customize_Section::print_template().
  306.      *
  307.      * @since 3.4.0
  308.      */
  309.     protected function render() {}
  310.  
  311.     /**
  312.      * Render the section's JS template.
  313.      *
  314.      * This function is only run for section types that have been registered with
  315.      * WP_Customize_Manager::register_section_type().
  316.      *
  317.      * @since 4.3.0
  318.      *
  319.      * @see WP_Customize_Manager::render_template()
  320.      */
  321.     public function print_template() {
  322.         ?>
  323.         <script type="text/html" id="tmpl-customize-section-<?php echo $this->type; ?>">
  324.             <?php $this->render_template(); ?>
  325.         </script>
  326.         <?php
  327.     }
  328.  
  329.     /**
  330.      * An Underscore (JS) template for rendering this section.
  331.      *
  332.      * Class variables for this section class are available in the `data` JS object;
  333.      * export custom variables by overriding WP_Customize_Section::json().
  334.      *
  335.      * @since 4.3.0
  336.      *
  337.      * @see WP_Customize_Section::print_template()
  338.      */
  339.     protected function render_template() {
  340.         ?>
  341.         <li id="accordion-section-{{ data.id }}" class="accordion-section control-section control-section-{{ data.type }}">
  342.             <h3 class="accordion-section-title" tabindex="0">
  343.                 {{ data.title }}
  344.                 <span class="screen-reader-text"><?php _e( 'Press return or enter to open this section' ); ?></span>
  345.             </h3>
  346.             <ul class="accordion-section-content">
  347.                 <li class="customize-section-description-container section-meta <# if ( data.description_hidden ) { #>customize-info<# } #>">
  348.                     <div class="customize-section-title">
  349.                         <button class="customize-section-back" tabindex="-1">
  350.                             <span class="screen-reader-text"><?php _e( 'Back' ); ?></span>
  351.                         </button>
  352.                         <h3>
  353.                             <span class="customize-action">
  354.                                 {{{ data.customizeAction }}}
  355.                             </span>
  356.                             {{ data.title }}
  357.                         </h3>
  358.                         <# if ( data.description && data.description_hidden ) { #>
  359.                             <button type="button" class="customize-help-toggle dashicons dashicons-editor-help" aria-expanded="false"><span class="screen-reader-text"><?php _e( 'Help' ); ?></span></button>
  360.                             <div class="description customize-section-description">
  361.                                 {{{ data.description }}}
  362.                             </div>
  363.                         <# } #>
  364.  
  365.                         <div class="customize-control-notifications-container"></div>
  366.                     </div>
  367.  
  368.                     <# if ( data.description && ! data.description_hidden ) { #>
  369.                         <div class="description customize-section-description">
  370.                             {{{ data.description }}}
  371.                         </div>
  372.                     <# } #>
  373.                 </li>
  374.             </ul>
  375.         </li>
  376.         <?php
  377.     }
  378. }
  379.  
  380. /** WP_Customize_Themes_Section class */
  381. require_once( ABSPATH . WPINC . '/customize/class-wp-customize-themes-section.php' );
  382.  
  383. /** WP_Customize_Sidebar_Section class */
  384. require_once( ABSPATH . WPINC . '/customize/class-wp-customize-sidebar-section.php' );
  385.  
  386. /** WP_Customize_Nav_Menu_Section class */
  387. require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-section.php' );
  388.  
  389. /**
  390.  * WP_Customize_New_Menu_Section class
  391.  *
  392.  * As this file is deprecated, it will trigger a deprecation notice if instantiated. In a subsequent
  393.  * release, the require_once() here will be removed and _deprecated_file() will be called if file is
  394.  * required at all.
  395.  *
  396.  * @deprecated 4.9.0 This file is no longer used due to new menu creation UX.
  397.  */
  398. require_once( ABSPATH . WPINC . '/customize/class-wp-customize-new-menu-section.php' );
  399.