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. * Show UI for adding new content, currently only used for the dropdown-pages control. 
  96. * @since 4.7.0 
  97. * @access public 
  98. * @var bool 
  99. */ 
  100. public $allow_addition = false; 
  101.  
  102. /** 
  103. * @deprecated It is better to just call the json() method 
  104. * @access public 
  105. * @var array 
  106. */ 
  107. public $json = array(); 
  108.  
  109. /** 
  110. * @access public 
  111. * @var string 
  112. */ 
  113. public $type = 'text'; 
  114.  
  115. /** 
  116. * Callback. 
  117. * @since 4.0.0 
  118. * @access public 
  119. * @see WP_Customize_Control::active() 
  120. * @var callable Callback is called with one argument, the instance of 
  121. * WP_Customize_Control, and returns bool to indicate whether 
  122. * the control is active (such as it relates to the URL 
  123. * currently being previewed). 
  124. */ 
  125. public $active_callback = ''; 
  126.  
  127. /** 
  128. * Constructor. 
  129. * Supplied `$args` override class property defaults. 
  130. * If `$args['settings']` is not defined, use the $id as the setting ID. 
  131. * @since 3.4.0 
  132. * @param WP_Customize_Manager $manager Customizer bootstrap instance. 
  133. * @param string $id Control ID. 
  134. * @param array $args { 
  135. * Optional. Arguments to override class property defaults. 
  136. * @type int $instance_number Order in which this instance was created in relation 
  137. * to other instances. 
  138. * @type WP_Customize_Manager $manager Customizer bootstrap instance. 
  139. * @type string $id Control ID. 
  140. * @type array $settings All settings tied to the control. If undefined, `$id` will 
  141. * be used. 
  142. * @type string $setting The primary setting for the control (if there is one). 
  143. * Default 'default'. 
  144. * @type int $priority Order priority to load the control. Default 10. 
  145. * @type string $section Section the control belongs to. Default empty. 
  146. * @type string $label Label for the control. Default empty. 
  147. * @type string $description Description for the control. Default empty. 
  148. * @type array $choices List of choices for 'radio' or 'select' type controls, where 
  149. * values are the keys, and labels are the values. 
  150. * Default empty array. 
  151. * @type array $input_attrs List of custom input attributes for control output, where 
  152. * attribute names are the keys and values are the values. Not 
  153. * used for 'checkbox', 'radio', 'select', 'textarea', or 
  154. * 'dropdown-pages' control types. Default empty array. 
  155. * @type array $json Deprecated. Use WP_Customize_Control::json() instead. 
  156. * @type string $type Control type. Core controls include 'text', 'checkbox',  
  157. * 'textarea', 'radio', 'select', and 'dropdown-pages'. Additional 
  158. * input types such as 'email', 'url', 'number', 'hidden', and 
  159. * 'date' are supported implicitly. Default 'text'. 
  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. $this->manager = $manager; 
  169. $this->id = $id; 
  170. if ( empty( $this->active_callback ) ) { 
  171. $this->active_callback = array( $this, 'active_callback' ); 
  172. self::$instance_count += 1; 
  173. $this->instance_number = self::$instance_count; 
  174.  
  175. // Process settings. 
  176. if ( ! isset( $this->settings ) ) { 
  177. $this->settings = $id; 
  178.  
  179. $settings = array(); 
  180. if ( is_array( $this->settings ) ) { 
  181. foreach ( $this->settings as $key => $setting ) { 
  182. $settings[ $key ] = $this->manager->get_setting( $setting ); 
  183. } else if ( is_string( $this->settings ) ) { 
  184. $this->setting = $this->manager->get_setting( $this->settings ); 
  185. $settings['default'] = $this->setting; 
  186. $this->settings = $settings; 
  187.  
  188. /** 
  189. * Enqueue control related scripts/styles. 
  190. * @since 3.4.0 
  191. */ 
  192. public function enqueue() {} 
  193.  
  194. /** 
  195. * Check whether control is active to current Customizer preview. 
  196. * @since 4.0.0 
  197. * @access public 
  198. * @return bool Whether the control is active to the current preview. 
  199. */ 
  200. final public function active() { 
  201. $control = $this; 
  202. $active = call_user_func( $this->active_callback, $this ); 
  203.  
  204. /** 
  205. * Filters response of WP_Customize_Control::active(). 
  206. * @since 4.0.0 
  207. * @param bool $active Whether the Customizer control is active. 
  208. * @param WP_Customize_Control $control WP_Customize_Control instance. 
  209. */ 
  210. $active = apply_filters( 'customize_control_active', $active, $control ); 
  211.  
  212. return $active; 
  213.  
  214. /** 
  215. * Default callback used when invoking WP_Customize_Control::active(). 
  216. * Subclasses can override this with their specific logic, or they may 
  217. * provide an 'active_callback' argument to the constructor. 
  218. * @since 4.0.0 
  219. * @access public 
  220. * @return true Always true. 
  221. */ 
  222. public function active_callback() { 
  223. return true; 
  224.  
  225. /** 
  226. * Fetch a setting's value. 
  227. * Grabs the main setting by default. 
  228. * @since 3.4.0 
  229. * @param string $setting_key 
  230. * @return mixed The requested setting's value, if the setting exists. 
  231. */ 
  232. final public function value( $setting_key = 'default' ) { 
  233. if ( isset( $this->settings[ $setting_key ] ) ) { 
  234. return $this->settings[ $setting_key ]->value(); 
  235.  
  236. /** 
  237. * Refresh the parameters passed to the JavaScript via JSON. 
  238. * @since 3.4.0 
  239. */ 
  240. public function to_json() { 
  241. $this->json['settings'] = array(); 
  242. foreach ( $this->settings as $key => $setting ) { 
  243. $this->json['settings'][ $key ] = $setting->id; 
  244.  
  245. $this->json['type'] = $this->type; 
  246. $this->json['priority'] = $this->priority; 
  247. $this->json['active'] = $this->active(); 
  248. $this->json['section'] = $this->section; 
  249. $this->json['content'] = $this->get_content(); 
  250. $this->json['label'] = $this->label; 
  251. $this->json['description'] = $this->description; 
  252. $this->json['instanceNumber'] = $this->instance_number; 
  253.  
  254. if ( 'dropdown-pages' === $this->type ) { 
  255. $this->json['allow_addition'] = $this->allow_addition; 
  256.  
  257. /** 
  258. * Get the data to export to the client via JSON. 
  259. * @since 4.1.0 
  260. * @return array Array of parameters passed to the JavaScript. 
  261. */ 
  262. public function json() { 
  263. $this->to_json(); 
  264. return $this->json; 
  265.  
  266. /** 
  267. * Checks if the user can use this control. 
  268. * Returns false if the user cannot manipulate one of the associated settings,  
  269. * or if one of the associated settings does not exist. Also returns false if 
  270. * the associated section does not exist or if its capability check returns 
  271. * false. 
  272. * @since 3.4.0 
  273. * @return bool False if theme doesn't support the control or user doesn't have the required permissions, otherwise true. 
  274. */ 
  275. final public function check_capabilities() { 
  276. if ( ! empty( $this->capability ) && ! current_user_can( $this->capability ) ) { 
  277. return false; 
  278.  
  279. foreach ( $this->settings as $setting ) { 
  280. if ( ! $setting || ! $setting->check_capabilities() ) { 
  281. return false; 
  282.  
  283. $section = $this->manager->get_section( $this->section ); 
  284. if ( isset( $section ) && ! $section->check_capabilities() ) { 
  285. return false; 
  286.  
  287. return true; 
  288.  
  289. /** 
  290. * Get the control's content for insertion into the Customizer pane. 
  291. * @since 4.1.0 
  292. * @return string Contents of the control. 
  293. */ 
  294. final public function get_content() { 
  295. ob_start(); 
  296. $this->maybe_render(); 
  297. return trim( ob_get_clean() ); 
  298.  
  299. /** 
  300. * Check capabilities and render the control. 
  301. * @since 3.4.0 
  302. * @uses WP_Customize_Control::render() 
  303. */ 
  304. final public function maybe_render() { 
  305. if ( ! $this->check_capabilities() ) 
  306. return; 
  307.  
  308. /** 
  309. * Fires just before the current Customizer control is rendered. 
  310. * @since 3.4.0 
  311. * @param WP_Customize_Control $this WP_Customize_Control instance. 
  312. */ 
  313. do_action( 'customize_render_control', $this ); 
  314.  
  315. /** 
  316. * Fires just before a specific Customizer control is rendered. 
  317. * The dynamic portion of the hook name, `$this->id`, refers to 
  318. * the control ID. 
  319. * @since 3.4.0 
  320. * @param WP_Customize_Control $this WP_Customize_Control instance. 
  321. */ 
  322. do_action( "customize_render_control_{$this->id}", $this ); 
  323.  
  324. $this->render(); 
  325.  
  326. /** 
  327. * Renders the control wrapper and calls $this->render_content() for the internals. 
  328. * @since 3.4.0 
  329. */ 
  330. protected function render() { 
  331. $id = 'customize-control-' . str_replace( array( '[', ']' ), array( '-', '' ), $this->id ); 
  332. $class = 'customize-control customize-control-' . $this->type; 
  333.  
  334. ?><li id="<?php echo esc_attr( $id ); ?>" class="<?php echo esc_attr( $class ); ?>"> 
  335. <?php $this->render_content(); ?> 
  336. </li><?php 
  337.  
  338. /** 
  339. * Get the data link attribute for a setting. 
  340. * @since 3.4.0 
  341. * @param string $setting_key 
  342. * @return string Data link parameter, if $setting_key is a valid setting, empty string otherwise. 
  343. */ 
  344. public function get_link( $setting_key = 'default' ) { 
  345. if ( ! isset( $this->settings[ $setting_key ] ) ) 
  346. return ''; 
  347.  
  348. return 'data-customize-setting-link="' . esc_attr( $this->settings[ $setting_key ]->id ) . '"'; 
  349.  
  350. /** 
  351. * Render the data link attribute for the control's input element. 
  352. * @since 3.4.0 
  353. * @uses WP_Customize_Control::get_link() 
  354. * @param string $setting_key 
  355. */ 
  356. public function link( $setting_key = 'default' ) { 
  357. echo $this->get_link( $setting_key ); 
  358.  
  359. /** 
  360. * Render the custom attributes for the control's input element. 
  361. * @since 4.0.0 
  362. * @access public 
  363. */ 
  364. public function input_attrs() { 
  365. foreach ( $this->input_attrs as $attr => $value ) { 
  366. echo $attr . '="' . esc_attr( $value ) . '" '; 
  367.  
  368. /** 
  369. * Render the control's content. 
  370. * Allows the content to be overridden without having to rewrite the wrapper in `$this::render()`. 
  371. * Supports basic input types `text`, `checkbox`, `textarea`, `radio`, `select` and `dropdown-pages`. 
  372. * Additional input types such as `email`, `url`, `number`, `hidden` and `date` are supported implicitly. 
  373. * Control content can alternately be rendered in JS. See WP_Customize_Control::print_template(). 
  374. * @since 3.4.0 
  375. */ 
  376. protected function render_content() { 
  377. switch( $this->type ) { 
  378. case 'checkbox': 
  379. ?> 
  380. <label> 
  381. <input type="checkbox" value="<?php echo esc_attr( $this->value() ); ?>" <?php $this->link(); checked( $this->value() ); ?> /> 
  382. <?php echo esc_html( $this->label ); ?> 
  383. <?php if ( ! empty( $this->description ) ) : ?> 
  384. <span class="description customize-control-description"><?php echo $this->description; ?></span> 
  385. <?php endif; ?> 
  386. </label> 
  387. <?php 
  388. break; 
  389. case 'radio': 
  390. if ( empty( $this->choices ) ) 
  391. return; 
  392.  
  393. $name = '_customize-radio-' . $this->id; 
  394.  
  395. if ( ! empty( $this->label ) ) : ?> 
  396. <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span> 
  397. <?php endif; 
  398. if ( ! empty( $this->description ) ) : ?> 
  399. <span class="description customize-control-description"><?php echo $this->description ; ?></span> 
  400. <?php endif; 
  401.  
  402. foreach ( $this->choices as $value => $label ) : 
  403. ?> 
  404. <label> 
  405. <input type="radio" value="<?php echo esc_attr( $value ); ?>" name="<?php echo esc_attr( $name ); ?>" <?php $this->link(); checked( $this->value(), $value ); ?> /> 
  406. <?php echo esc_html( $label ); ?><br/> 
  407. </label> 
  408. <?php 
  409. endforeach; 
  410. break; 
  411. case 'select': 
  412. if ( empty( $this->choices ) ) 
  413. return; 
  414.  
  415. ?> 
  416. <label> 
  417. <?php if ( ! empty( $this->label ) ) : ?> 
  418. <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span> 
  419. <?php endif; 
  420. if ( ! empty( $this->description ) ) : ?> 
  421. <span class="description customize-control-description"><?php echo $this->description; ?></span> 
  422. <?php endif; ?> 
  423.  
  424. <select <?php $this->link(); ?>> 
  425. <?php 
  426. foreach ( $this->choices as $value => $label ) 
  427. echo '<option value="' . esc_attr( $value ) . '"' . selected( $this->value(), $value, false ) . '>' . $label . '</option>'; 
  428. ?> 
  429. </select> 
  430. </label> 
  431. <?php 
  432. break; 
  433. case 'textarea': 
  434. ?> 
  435. <label> 
  436. <?php if ( ! empty( $this->label ) ) : ?> 
  437. <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span> 
  438. <?php endif; 
  439. if ( ! empty( $this->description ) ) : ?> 
  440. <span class="description customize-control-description"><?php echo $this->description; ?></span> 
  441. <?php endif; ?> 
  442. <textarea rows="5" <?php $this->input_attrs(); ?> <?php $this->link(); ?>><?php echo esc_textarea( $this->value() ); ?></textarea> 
  443. </label> 
  444. <?php 
  445. break; 
  446. case 'dropdown-pages': 
  447. ?> 
  448. <label> 
  449. <?php if ( ! empty( $this->label ) ) : ?> 
  450. <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span> 
  451. <?php endif; 
  452. if ( ! empty( $this->description ) ) : ?> 
  453. <span class="description customize-control-description"><?php echo $this->description; ?></span> 
  454. <?php endif; ?> 
  455.  
  456. <?php 
  457. $dropdown_name = '_customize-dropdown-pages-' . $this->id; 
  458. $show_option_none = __( '— Select —' ); 
  459. $option_none_value = '0'; 
  460. $dropdown = wp_dropdown_pages( 
  461. array( 
  462. 'name' => $dropdown_name,  
  463. 'echo' => 0,  
  464. 'show_option_none' => $show_option_none,  
  465. 'option_none_value' => $option_none_value,  
  466. 'selected' => $this->value(),  
  467. ); 
  468. if ( empty( $dropdown ) ) { 
  469. $dropdown = sprintf( '<select id="%1$s" name="%1$s">', esc_attr( $dropdown_name ) ); 
  470. $dropdown .= sprintf( '<option value="%1$s">%2$s</option>', esc_attr( $option_none_value ), esc_html( $show_option_none ) ); 
  471. $dropdown .= '</select>'; 
  472.  
  473. // Hackily add in the data link parameter. 
  474. $dropdown = str_replace( '<select', '<select ' . $this->get_link(), $dropdown ); 
  475.  
  476. // Even more hacikly add auto-draft page stubs. 
  477. // @todo Eventually this should be removed in favor of the pages being injected into the underlying get_pages() call. See <https://github.com/xwp/wp-customize-posts/pull/250>. 
  478. $nav_menus_created_posts_setting = $this->manager->get_setting( 'nav_menus_created_posts' ); 
  479. if ( $nav_menus_created_posts_setting && current_user_can( 'publish_pages' ) ) { 
  480. $auto_draft_page_options = ''; 
  481. foreach ( $nav_menus_created_posts_setting->value() as $auto_draft_page_id ) { 
  482. $post = get_post( $auto_draft_page_id ); 
  483. if ( $post && 'page' === $post->post_type ) { 
  484. $auto_draft_page_options .= sprintf( '<option value="%1$s">%2$s</option>', esc_attr( $post->ID ), esc_html( $post->post_title ) ); 
  485. if ( $auto_draft_page_options ) { 
  486. $dropdown = str_replace( '</select>', $auto_draft_page_options . '</select>', $dropdown ); 
  487.  
  488. echo $dropdown; 
  489. ?> 
  490. </label> 
  491. <?php if ( $this->allow_addition && current_user_can( 'publish_pages' ) && current_user_can( 'edit_theme_options' ) ) : // Currently tied to menus functionality. ?> 
  492. <button type="button" class="button-link add-new-toggle"><?php 
  493. /** translators: %s: add new page label */ 
  494. printf( __( '+ %s' ), get_post_type_object( 'page' )->labels->add_new_item ); 
  495. ?></button> 
  496. <div class="new-content-item"> 
  497. <label for="create-input-<?php echo $this->id; ?>"><span class="screen-reader-text"><?php _e( 'New page title' ); ?></span></label> 
  498. <input type="text" id="create-input-<?php echo $this->id; ?>" class="create-item-input" placeholder="<?php esc_attr_e( 'New page title…' ); ?>"> 
  499. <button type="button" class="button add-content"><?php _e( 'Add' ); ?></button> 
  500. </div> 
  501. <?php endif; 
  502. break; 
  503. default: 
  504. ?> 
  505. <label> 
  506. <?php if ( ! empty( $this->label ) ) : ?> 
  507. <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span> 
  508. <?php endif; 
  509. if ( ! empty( $this->description ) ) : ?> 
  510. <span class="description customize-control-description"><?php echo $this->description; ?></span> 
  511. <?php endif; ?> 
  512. <input type="<?php echo esc_attr( $this->type ); ?>" <?php $this->input_attrs(); ?> value="<?php echo esc_attr( $this->value() ); ?>" <?php $this->link(); ?> /> 
  513. </label> 
  514. <?php 
  515. break; 
  516.  
  517. /** 
  518. * Render the control's JS template. 
  519. * This function is only run for control types that have been registered with 
  520. * WP_Customize_Manager::register_control_type(). 
  521. * In the future, this will also print the template for the control's container 
  522. * element and be override-able. 
  523. * @since 4.1.0 
  524. */ 
  525. final public function print_template() { 
  526. ?> 
  527. <script type="text/html" id="tmpl-customize-control-<?php echo $this->type; ?>-content"> 
  528. <?php $this->content_template(); ?> 
  529. </script> 
  530. <?php 
  531.  
  532. /** 
  533. * An Underscore (JS) template for this control's content (but not its container). 
  534. * Class variables for this control class are available in the `data` JS object; 
  535. * export custom variables by overriding WP_Customize_Control::to_json(). 
  536. * @see WP_Customize_Control::print_template() 
  537. * @since 4.1.0 
  538. */ 
  539. protected function content_template() {} 
  540.