WP_Customize_Control

Customize Control class.

Defined (1)

The class is defined in the following location(s).

/wp-includes/class-wp-customize-control.php  
  1. class WP_Customize_Control { 
  2.  
  3. /** 
  4. * Incremented with each new class instantiation, then stored in $instance_number. 
  5. * Used when sorting two instances whose priorities are equal. 
  6. * @since 4.1.0 
  7. * @static 
  8. * @access protected 
  9. * @var int 
  10. */ 
  11. protected static $instance_count = 0; 
  12.  
  13. /** 
  14. * Order in which this instance was created in relation to other instances. 
  15. * @since 4.1.0 
  16. * @access public 
  17. * @var int 
  18. */ 
  19. public $instance_number; 
  20.  
  21. /** 
  22. * @access public 
  23. * @var WP_Customize_Manager 
  24. */ 
  25. public $manager; 
  26.  
  27. /** 
  28. * @access public 
  29. * @var string 
  30. */ 
  31. public $id; 
  32.  
  33. /** 
  34. * All settings tied to the control. 
  35. * @access public 
  36. * @var array 
  37. */ 
  38. public $settings; 
  39.  
  40. /** 
  41. * The primary setting for the control (if there is one). 
  42. * @access public 
  43. * @var string 
  44. */ 
  45. public $setting = 'default'; 
  46.  
  47. /** 
  48. * Capability required to use this control. 
  49. * Normally this is empty and the capability is derived from the capabilities 
  50. * of the associated `$settings`. 
  51. * @since 4.5.0 
  52. * @access public 
  53. * @var string 
  54. */ 
  55. public $capability; 
  56.  
  57. /** 
  58. * @access public 
  59. * @var int 
  60. */ 
  61. public $priority = 10; 
  62.  
  63. /** 
  64. * @access public 
  65. * @var string 
  66. */ 
  67. public $section = ''; 
  68.  
  69. /** 
  70. * @access public 
  71. * @var string 
  72. */ 
  73. public $label = ''; 
  74.  
  75. /** 
  76. * @access public 
  77. * @var string 
  78. */ 
  79. public $description = ''; 
  80.  
  81. /** 
  82. * @todo: Remove choices 
  83. * @access public 
  84. * @var array 
  85. */ 
  86. public $choices = array(); 
  87.  
  88. /** 
  89. * @access public 
  90. * @var array 
  91. */ 
  92. public $input_attrs = array(); 
  93.  
  94. /** 
  95. * @deprecated It is better to just call the json() method 
  96. * @access public 
  97. * @var array 
  98. */ 
  99. public $json = array(); 
  100.  
  101. /** 
  102. * @access public 
  103. * @var string 
  104. */ 
  105. public $type = 'text'; 
  106.  
  107. /** 
  108. * Callback. 
  109. * @since 4.0.0 
  110. * @access public 
  111. * @see WP_Customize_Control::active() 
  112. * @var callable Callback is called with one argument, the instance of 
  113. * WP_Customize_Control, and returns bool to indicate whether 
  114. * the control is active (such as it relates to the URL 
  115. * currently being previewed). 
  116. */ 
  117. public $active_callback = ''; 
  118.  
  119. /** 
  120. * Constructor. 
  121. * Supplied `$args` override class property defaults. 
  122. * If `$args['settings']` is not defined, use the $id as the setting ID. 
  123. * @since 3.4.0 
  124. * @param WP_Customize_Manager $manager Customizer bootstrap instance. 
  125. * @param string $id Control ID. 
  126. * @param array $args { 
  127. * Optional. Arguments to override class property defaults. 
  128. * @type int $instance_number Order in which this instance was created in relation 
  129. * to other instances. 
  130. * @type WP_Customize_Manager $manager Customizer bootstrap instance. 
  131. * @type string $id Control ID. 
  132. * @type array $settings All settings tied to the control. If undefined, `$id` will 
  133. * be used. 
  134. * @type string $setting The primary setting for the control (if there is one). 
  135. * Default 'default'. 
  136. * @type int $priority Order priority to load the control. Default 10. 
  137. * @type string $section Section the control belongs to. Default empty. 
  138. * @type string $label Label for the control. Default empty. 
  139. * @type string $description Description for the control. Default empty. 
  140. * @type array $choices List of choices for 'radio' or 'select' type controls, where 
  141. * values are the keys, and labels are the values. 
  142. * Default empty array. 
  143. * @type array $input_attrs List of custom input attributes for control output, where 
  144. * attribute names are the keys and values are the values. Not 
  145. * used for 'checkbox', 'radio', 'select', 'textarea', or 
  146. * 'dropdown-pages' control types. Default empty array. 
  147. * @type array $json Deprecated. Use WP_Customize_Control::json() instead. 
  148. * @type string $type Control type. Core controls include 'text', 'checkbox',  
  149. * 'textarea', 'radio', 'select', and 'dropdown-pages'. Additional 
  150. * input types such as 'email', 'url', 'number', 'hidden', and 
  151. * 'date' are supported implicitly. Default 'text'. 
  152. * } 
  153. */ 
  154. public function __construct( $manager, $id, $args = array() ) { 
  155. $keys = array_keys( get_object_vars( $this ) ); 
  156. foreach ( $keys as $key ) { 
  157. if ( isset( $args[ $key ] ) ) { 
  158. $this->$key = $args[ $key ]; 
  159.  
  160. $this->manager = $manager; 
  161. $this->id = $id; 
  162. if ( empty( $this->active_callback ) ) { 
  163. $this->active_callback = array( $this, 'active_callback' ); 
  164. self::$instance_count += 1; 
  165. $this->instance_number = self::$instance_count; 
  166.  
  167. // Process settings. 
  168. if ( ! isset( $this->settings ) ) { 
  169. $this->settings = $id; 
  170.  
  171. $settings = array(); 
  172. if ( is_array( $this->settings ) ) { 
  173. foreach ( $this->settings as $key => $setting ) { 
  174. $settings[ $key ] = $this->manager->get_setting( $setting ); 
  175. } else if ( is_string( $this->settings ) ) { 
  176. $this->setting = $this->manager->get_setting( $this->settings ); 
  177. $settings['default'] = $this->setting; 
  178. $this->settings = $settings; 
  179.  
  180. /** 
  181. * Enqueue control related scripts/styles. 
  182. * @since 3.4.0 
  183. */ 
  184. public function enqueue() {} 
  185.  
  186. /** 
  187. * Check whether control is active to current Customizer preview. 
  188. * @since 4.0.0 
  189. * @access public 
  190. * @return bool Whether the control is active to the current preview. 
  191. */ 
  192. final public function active() { 
  193. $control = $this; 
  194. $active = call_user_func( $this->active_callback, $this ); 
  195.  
  196. /** 
  197. * Filters response of WP_Customize_Control::active(). 
  198. * @since 4.0.0 
  199. * @param bool $active Whether the Customizer control is active. 
  200. * @param WP_Customize_Control $control WP_Customize_Control instance. 
  201. */ 
  202. $active = apply_filters( 'customize_control_active', $active, $control ); 
  203.  
  204. return $active; 
  205.  
  206. /** 
  207. * Default callback used when invoking WP_Customize_Control::active(). 
  208. * Subclasses can override this with their specific logic, or they may 
  209. * provide an 'active_callback' argument to the constructor. 
  210. * @since 4.0.0 
  211. * @access public 
  212. * @return true Always true. 
  213. */ 
  214. public function active_callback() { 
  215. return true; 
  216.  
  217. /** 
  218. * Fetch a setting's value. 
  219. * Grabs the main setting by default. 
  220. * @since 3.4.0 
  221. * @param string $setting_key 
  222. * @return mixed The requested setting's value, if the setting exists. 
  223. */ 
  224. final public function value( $setting_key = 'default' ) { 
  225. if ( isset( $this->settings[ $setting_key ] ) ) { 
  226. return $this->settings[ $setting_key ]->value(); 
  227.  
  228. /** 
  229. * Refresh the parameters passed to the JavaScript via JSON. 
  230. * @since 3.4.0 
  231. */ 
  232. public function to_json() { 
  233. $this->json['settings'] = array(); 
  234. foreach ( $this->settings as $key => $setting ) { 
  235. $this->json['settings'][ $key ] = $setting->id; 
  236.  
  237. $this->json['type'] = $this->type; 
  238. $this->json['priority'] = $this->priority; 
  239. $this->json['active'] = $this->active(); 
  240. $this->json['section'] = $this->section; 
  241. $this->json['content'] = $this->get_content(); 
  242. $this->json['label'] = $this->label; 
  243. $this->json['description'] = $this->description; 
  244. $this->json['instanceNumber'] = $this->instance_number; 
  245.  
  246. /** 
  247. * Get the data to export to the client via JSON. 
  248. * @since 4.1.0 
  249. * @return array Array of parameters passed to the JavaScript. 
  250. */ 
  251. public function json() { 
  252. $this->to_json(); 
  253. return $this->json; 
  254.  
  255. /** 
  256. * Checks if the user can use this control. 
  257. * Returns false if the user cannot manipulate one of the associated settings,  
  258. * or if one of the associated settings does not exist. Also returns false if 
  259. * the associated section does not exist or if its capability check returns 
  260. * false. 
  261. * @since 3.4.0 
  262. * @return bool False if theme doesn't support the control or user doesn't have the required permissions, otherwise true. 
  263. */ 
  264. final public function check_capabilities() { 
  265. if ( ! empty( $this->capability ) && ! current_user_can( $this->capability ) ) { 
  266. return false; 
  267.  
  268. foreach ( $this->settings as $setting ) { 
  269. if ( ! $setting || ! $setting->check_capabilities() ) { 
  270. return false; 
  271.  
  272. $section = $this->manager->get_section( $this->section ); 
  273. if ( isset( $section ) && ! $section->check_capabilities() ) { 
  274. return false; 
  275.  
  276. return true; 
  277.  
  278. /** 
  279. * Get the control's content for insertion into the Customizer pane. 
  280. * @since 4.1.0 
  281. * @return string Contents of the control. 
  282. */ 
  283. final public function get_content() { 
  284. ob_start(); 
  285. $this->maybe_render(); 
  286. return trim( ob_get_clean() ); 
  287.  
  288. /** 
  289. * Check capabilities and render the control. 
  290. * @since 3.4.0 
  291. * @uses WP_Customize_Control::render() 
  292. */ 
  293. final public function maybe_render() { 
  294. if ( ! $this->check_capabilities() ) 
  295. return; 
  296.  
  297. /** 
  298. * Fires just before the current Customizer control is rendered. 
  299. * @since 3.4.0 
  300. * @param WP_Customize_Control $this WP_Customize_Control instance. 
  301. */ 
  302. do_action( 'customize_render_control', $this ); 
  303.  
  304. /** 
  305. * Fires just before a specific Customizer control is rendered. 
  306. * The dynamic portion of the hook name, `$this->id`, refers to 
  307. * the control ID. 
  308. * @since 3.4.0 
  309. * @param WP_Customize_Control $this WP_Customize_Control instance. 
  310. */ 
  311. do_action( 'customize_render_control_' . $this->id, $this ); 
  312.  
  313. $this->render(); 
  314.  
  315. /** 
  316. * Renders the control wrapper and calls $this->render_content() for the internals. 
  317. * @since 3.4.0 
  318. */ 
  319. protected function render() { 
  320. $id = 'customize-control-' . str_replace( array( '[', ']' ), array( '-', '' ), $this->id ); 
  321. $class = 'customize-control customize-control-' . $this->type; 
  322.  
  323. ?><li id="<?php echo esc_attr( $id ); ?>" class="<?php echo esc_attr( $class ); ?>"> 
  324. <?php $this->render_content(); ?> 
  325. </li><?php 
  326.  
  327. /** 
  328. * Get the data link attribute for a setting. 
  329. * @since 3.4.0 
  330. * @param string $setting_key 
  331. * @return string Data link parameter, if $setting_key is a valid setting, empty string otherwise. 
  332. */ 
  333. public function get_link( $setting_key = 'default' ) { 
  334. if ( ! isset( $this->settings[ $setting_key ] ) ) 
  335. return ''; 
  336.  
  337. return 'data-customize-setting-link="' . esc_attr( $this->settings[ $setting_key ]->id ) . '"'; 
  338.  
  339. /** 
  340. * Render the data link attribute for the control's input element. 
  341. * @since 3.4.0 
  342. * @uses WP_Customize_Control::get_link() 
  343. * @param string $setting_key 
  344. */ 
  345. public function link( $setting_key = 'default' ) { 
  346. echo $this->get_link( $setting_key ); 
  347.  
  348. /** 
  349. * Render the custom attributes for the control's input element. 
  350. * @since 4.0.0 
  351. * @access public 
  352. */ 
  353. public function input_attrs() { 
  354. foreach ( $this->input_attrs as $attr => $value ) { 
  355. echo $attr . '="' . esc_attr( $value ) . '" '; 
  356.  
  357. /** 
  358. * Render the control's content. 
  359. * Allows the content to be overriden without having to rewrite the wrapper in `$this::render()`. 
  360. * Supports basic input types `text`, `checkbox`, `textarea`, `radio`, `select` and `dropdown-pages`. 
  361. * Additional input types such as `email`, `url`, `number`, `hidden` and `date` are supported implicitly. 
  362. * Control content can alternately be rendered in JS. See WP_Customize_Control::print_template(). 
  363. * @since 3.4.0 
  364. */ 
  365. protected function render_content() { 
  366. switch( $this->type ) { 
  367. case 'checkbox': 
  368. ?> 
  369. <label> 
  370. <input type="checkbox" value="<?php echo esc_attr( $this->value() ); ?>" <?php $this->link(); checked( $this->value() ); ?> /> 
  371. <?php echo esc_html( $this->label ); ?> 
  372. <?php if ( ! empty( $this->description ) ) : ?> 
  373. <span class="description customize-control-description"><?php echo $this->description; ?></span> 
  374. <?php endif; ?> 
  375. </label> 
  376. <?php 
  377. break; 
  378. case 'radio': 
  379. if ( empty( $this->choices ) ) 
  380. return; 
  381.  
  382. $name = '_customize-radio-' . $this->id; 
  383.  
  384. if ( ! empty( $this->label ) ) : ?> 
  385. <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span> 
  386. <?php endif; 
  387. if ( ! empty( $this->description ) ) : ?> 
  388. <span class="description customize-control-description"><?php echo $this->description ; ?></span> 
  389. <?php endif; 
  390.  
  391. foreach ( $this->choices as $value => $label ) : 
  392. ?> 
  393. <label> 
  394. <input type="radio" value="<?php echo esc_attr( $value ); ?>" name="<?php echo esc_attr( $name ); ?>" <?php $this->link(); checked( $this->value(), $value ); ?> /> 
  395. <?php echo esc_html( $label ); ?><br/> 
  396. </label> 
  397. <?php 
  398. endforeach; 
  399. break; 
  400. case 'select': 
  401. if ( empty( $this->choices ) ) 
  402. return; 
  403.  
  404. ?> 
  405. <label> 
  406. <?php if ( ! empty( $this->label ) ) : ?> 
  407. <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span> 
  408. <?php endif; 
  409. if ( ! empty( $this->description ) ) : ?> 
  410. <span class="description customize-control-description"><?php echo $this->description; ?></span> 
  411. <?php endif; ?> 
  412.  
  413. <select <?php $this->link(); ?>> 
  414. <?php 
  415. foreach ( $this->choices as $value => $label ) 
  416. echo '<option value="' . esc_attr( $value ) . '"' . selected( $this->value(), $value, false ) . '>' . $label . '</option>'; 
  417. ?> 
  418. </select> 
  419. </label> 
  420. <?php 
  421. break; 
  422. case 'textarea': 
  423. ?> 
  424. <label> 
  425. <?php if ( ! empty( $this->label ) ) : ?> 
  426. <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span> 
  427. <?php endif; 
  428. if ( ! empty( $this->description ) ) : ?> 
  429. <span class="description customize-control-description"><?php echo $this->description; ?></span> 
  430. <?php endif; ?> 
  431. <textarea rows="5" <?php $this->link(); ?>><?php echo esc_textarea( $this->value() ); ?></textarea> 
  432. </label> 
  433. <?php 
  434. break; 
  435. case 'dropdown-pages': 
  436. ?> 
  437. <label> 
  438. <?php if ( ! empty( $this->label ) ) : ?> 
  439. <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span> 
  440. <?php endif; 
  441. if ( ! empty( $this->description ) ) : ?> 
  442. <span class="description customize-control-description"><?php echo $this->description; ?></span> 
  443. <?php endif; ?> 
  444.  
  445. <?php $dropdown = wp_dropdown_pages( 
  446. array( 
  447. 'name' => '_customize-dropdown-pages-' . $this->id,  
  448. 'echo' => 0,  
  449. 'show_option_none' => __( '— Select —' ),  
  450. 'option_none_value' => '0',  
  451. 'selected' => $this->value(),  
  452. ); 
  453.  
  454. // Hackily add in the data link parameter. 
  455. $dropdown = str_replace( '<select', '<select ' . $this->get_link(), $dropdown ); 
  456. echo $dropdown; 
  457. ?> 
  458. </label> 
  459. <?php 
  460. break; 
  461. default: 
  462. ?> 
  463. <label> 
  464. <?php if ( ! empty( $this->label ) ) : ?> 
  465. <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span> 
  466. <?php endif; 
  467. if ( ! empty( $this->description ) ) : ?> 
  468. <span class="description customize-control-description"><?php echo $this->description; ?></span> 
  469. <?php endif; ?> 
  470. <input type="<?php echo esc_attr( $this->type ); ?>" <?php $this->input_attrs(); ?> value="<?php echo esc_attr( $this->value() ); ?>" <?php $this->link(); ?> /> 
  471. </label> 
  472. <?php 
  473. break; 
  474.  
  475. /** 
  476. * Render the control's JS template. 
  477. * This function is only run for control types that have been registered with 
  478. * WP_Customize_Manager::register_control_type(). 
  479. * In the future, this will also print the template for the control's container 
  480. * element and be override-able. 
  481. * @since 4.1.0 
  482. */ 
  483. final public function print_template() { 
  484. ?> 
  485. <script type="text/html" id="tmpl-customize-control-<?php echo $this->type; ?>-content"> 
  486. <?php $this->content_template(); ?> 
  487. </script> 
  488. <?php 
  489.  
  490. /** 
  491. * An Underscore (JS) template for this control's content (but not its container). 
  492. * Class variables for this control class are available in the `data` JS object; 
  493. * export custom variables by overriding WP_Customize_Control::to_json(). 
  494. * @see WP_Customize_Control::print_template() 
  495. * @since 4.1.0 
  496. */ 
  497. protected function content_template() {} 
  498.