/wp-includes/class-wp-customize-section.php

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