WP_Customize_Setting

Customize Setting class.

Defined (1)

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

/wp-includes/class-wp-customize-setting.php  
  1. class WP_Customize_Setting { 
  2. /** 
  3. * @access public 
  4. * @var WP_Customize_Manager 
  5. */ 
  6. public $manager; 
  7.  
  8. /** 
  9. * Unique string identifier for the setting. 
  10. * @access public 
  11. * @var string 
  12. */ 
  13. public $id; 
  14.  
  15. /** 
  16. * @access public 
  17. * @var string 
  18. */ 
  19. public $type = 'theme_mod'; 
  20.  
  21. /** 
  22. * Capability required to edit this setting. 
  23. * @var string 
  24. */ 
  25. public $capability = 'edit_theme_options'; 
  26.  
  27. /** 
  28. * Feature a theme is required to support to enable this setting. 
  29. * @access public 
  30. * @var string 
  31. */ 
  32. public $theme_supports = ''; 
  33. public $default = ''; 
  34. public $transport = 'refresh'; 
  35.  
  36. /** 
  37. * Server-side sanitization callback for the setting's value. 
  38. * @var callback 
  39. */ 
  40. public $validate_callback = ''; 
  41. public $sanitize_callback = ''; 
  42. public $sanitize_js_callback = ''; 
  43.  
  44. /** 
  45. * Whether or not the setting is initially dirty when created. 
  46. * This is used to ensure that a setting will be sent from the pane to the 
  47. * preview when loading the Customizer. Normally a setting only is synced to 
  48. * the preview if it has been changed. This allows the setting to be sent 
  49. * from the start. 
  50. * @since 4.2.0 
  51. * @access public 
  52. * @var bool 
  53. */ 
  54. public $dirty = false; 
  55.  
  56. /** 
  57. * @var array 
  58. */ 
  59. protected $id_data = array(); 
  60.  
  61. /** 
  62. * Whether or not preview() was called. 
  63. * @since 4.4.0 
  64. * @access protected 
  65. * @var bool 
  66. */ 
  67. protected $is_previewed = false; 
  68.  
  69. /** 
  70. * Cache of multidimensional values to improve performance. 
  71. * @since 4.4.0 
  72. * @access protected 
  73. * @var array 
  74. * @static 
  75. */ 
  76. protected static $aggregated_multidimensionals = array(); 
  77.  
  78. /** 
  79. * Whether the multidimensional setting is aggregated. 
  80. * @since 4.4.0 
  81. * @access protected 
  82. * @var bool 
  83. */ 
  84. protected $is_multidimensional_aggregated = false; 
  85.  
  86. /** 
  87. * Constructor. 
  88. * Any supplied $args override class property defaults. 
  89. * @since 3.4.0 
  90. * @param WP_Customize_Manager $manager 
  91. * @param string $id An specific ID of the setting. Can be a 
  92. * theme mod or option name. 
  93. * @param array $args Setting arguments. 
  94. */ 
  95. public function __construct( $manager, $id, $args = array() ) { 
  96. $keys = array_keys( get_object_vars( $this ) ); 
  97. foreach ( $keys as $key ) { 
  98. if ( isset( $args[ $key ] ) ) { 
  99. $this->$key = $args[ $key ]; 
  100.  
  101. $this->manager = $manager; 
  102. $this->id = $id; 
  103.  
  104. // Parse the ID for array keys. 
  105. $this->id_data['keys'] = preg_split( '/\[/', str_replace( ']', '', $this->id ) ); 
  106. $this->id_data['base'] = array_shift( $this->id_data['keys'] ); 
  107.  
  108. // Rebuild the ID. 
  109. $this->id = $this->id_data[ 'base' ]; 
  110. if ( ! empty( $this->id_data[ 'keys' ] ) ) { 
  111. $this->id .= '[' . implode( '][', $this->id_data['keys'] ) . ']'; 
  112.  
  113. if ( $this->validate_callback ) { 
  114. add_filter( "customize_validate_{$this->id}", $this->validate_callback, 10, 3 ); 
  115. if ( $this->sanitize_callback ) { 
  116. add_filter( "customize_sanitize_{$this->id}", $this->sanitize_callback, 10, 2 ); 
  117. if ( $this->sanitize_js_callback ) { 
  118. add_filter( "customize_sanitize_js_{$this->id}", $this->sanitize_js_callback, 10, 2 ); 
  119.  
  120. if ( 'option' === $this->type || 'theme_mod' === $this->type ) { 
  121. // Other setting types can opt-in to aggregate multidimensional explicitly. 
  122. $this->aggregate_multidimensional(); 
  123.  
  124. // Allow option settings to indicate whether they should be autoloaded. 
  125. if ( 'option' === $this->type && isset( $args['autoload'] ) ) { 
  126. self::$aggregated_multidimensionals[ $this->type ][ $this->id_data['base'] ]['autoload'] = $args['autoload']; 
  127.  
  128. /** 
  129. * Get parsed ID data for multidimensional setting. 
  130. * @since 4.4.0 
  131. * @access public 
  132. * @return array { 
  133. * ID data for multidimensional setting. 
  134. * @type string $base ID base 
  135. * @type array $keys Keys for multidimensional array. 
  136. * } 
  137. */ 
  138. final public function id_data() { 
  139. return $this->id_data; 
  140.  
  141. /** 
  142. * Set up the setting for aggregated multidimensional values. 
  143. * When a multidimensional setting gets aggregated, all of its preview and update 
  144. * calls get combined into one call, greatly improving performance. 
  145. * @since 4.4.0 
  146. * @access protected 
  147. */ 
  148. protected function aggregate_multidimensional() { 
  149. $id_base = $this->id_data['base']; 
  150. if ( ! isset( self::$aggregated_multidimensionals[ $this->type ] ) ) { 
  151. self::$aggregated_multidimensionals[ $this->type ] = array(); 
  152. if ( ! isset( self::$aggregated_multidimensionals[ $this->type ][ $id_base ] ) ) { 
  153. self::$aggregated_multidimensionals[ $this->type ][ $id_base ] = array( 
  154. 'previewed_instances' => array(), // Calling preview() will add the $setting to the array. 
  155. 'preview_applied_instances' => array(), // Flags for which settings have had their values applied. 
  156. 'root_value' => $this->get_root_value( array() ), // Root value for initial state, manipulated by preview and update calls. 
  157. ); 
  158.  
  159. if ( ! empty( $this->id_data['keys'] ) ) { 
  160. // Note the preview-applied flag is cleared at priority 9 to ensure it is cleared before a deferred-preview runs. 
  161. add_action( "customize_post_value_set_{$this->id}", array( $this, '_clear_aggregated_multidimensional_preview_applied_flag' ), 9 ); 
  162. $this->is_multidimensional_aggregated = true; 
  163.  
  164. /** 
  165. * Reset `$aggregated_multidimensionals` static variable. 
  166. * This is intended only for use by unit tests. 
  167. * @since 4.5.0 
  168. * @access public 
  169. * @ignore 
  170. */ 
  171. static public function reset_aggregated_multidimensionals() { 
  172. self::$aggregated_multidimensionals = array(); 
  173.  
  174. /** 
  175. * The ID for the current site when the preview() method was called. 
  176. * @since 4.2.0 
  177. * @access protected 
  178. * @var int 
  179. */ 
  180. protected $_previewed_blog_id; 
  181.  
  182. /** 
  183. * Return true if the current site is not the same as the previewed site. 
  184. * @since 4.2.0 
  185. * @access public 
  186. * @return bool If preview() has been called. 
  187. */ 
  188. public function is_current_blog_previewed() { 
  189. if ( ! isset( $this->_previewed_blog_id ) ) { 
  190. return false; 
  191. return ( get_current_blog_id() === $this->_previewed_blog_id ); 
  192.  
  193. /** 
  194. * Original non-previewed value stored by the preview method. 
  195. * @see WP_Customize_Setting::preview() 
  196. * @since 4.1.1 
  197. * @var mixed 
  198. */ 
  199. protected $_original_value; 
  200.  
  201. /** 
  202. * Add filters to supply the setting's value when accessed. 
  203. * If the setting already has a pre-existing value and there is no incoming 
  204. * post value for the setting, then this method will short-circuit since 
  205. * there is no change to preview. 
  206. * @since 3.4.0 
  207. * @since 4.4.0 Added boolean return value. 
  208. * @access public 
  209. * @return bool False when preview short-circuits due no change needing to be previewed. 
  210. */ 
  211. public function preview() { 
  212. if ( ! isset( $this->_previewed_blog_id ) ) { 
  213. $this->_previewed_blog_id = get_current_blog_id(); 
  214.  
  215. // Prevent re-previewing an already-previewed setting. 
  216. if ( $this->is_previewed ) { 
  217. return true; 
  218.  
  219. $id_base = $this->id_data['base']; 
  220. $is_multidimensional = ! empty( $this->id_data['keys'] ); 
  221. $multidimensional_filter = array( $this, '_multidimensional_preview_filter' ); 
  222.  
  223. /** 
  224. * Check if the setting has a pre-existing value (an isset check),  
  225. * and if doesn't have any incoming post value. If both checks are true,  
  226. * then the preview short-circuits because there is nothing that needs 
  227. * to be previewed. 
  228. */ 
  229. $undefined = new stdClass(); 
  230. $needs_preview = ( $undefined !== $this->post_value( $undefined ) ); 
  231. $value = null; 
  232.  
  233. // Since no post value was defined, check if we have an initial value set. 
  234. if ( ! $needs_preview ) { 
  235. if ( $this->is_multidimensional_aggregated ) { 
  236. $root = self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value']; 
  237. $value = $this->multidimensional_get( $root, $this->id_data['keys'], $undefined ); 
  238. } else { 
  239. $default = $this->default; 
  240. $this->default = $undefined; // Temporarily set default to undefined so we can detect if existing value is set. 
  241. $value = $this->value(); 
  242. $this->default = $default; 
  243. $needs_preview = ( $undefined === $value ); // Because the default needs to be supplied. 
  244.  
  245. // If the setting does not need previewing now, defer to when it has a value to preview. 
  246. if ( ! $needs_preview ) { 
  247. if ( ! has_action( "customize_post_value_set_{$this->id}", array( $this, 'preview' ) ) ) { 
  248. add_action( "customize_post_value_set_{$this->id}", array( $this, 'preview' ) ); 
  249. return false; 
  250.  
  251. switch ( $this->type ) { 
  252. case 'theme_mod' : 
  253. if ( ! $is_multidimensional ) { 
  254. add_filter( "theme_mod_{$id_base}", array( $this, '_preview_filter' ) ); 
  255. } else { 
  256. if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) { 
  257. // Only add this filter once for this ID base. 
  258. add_filter( "theme_mod_{$id_base}", $multidimensional_filter ); 
  259. self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'][ $this->id ] = $this; 
  260. break; 
  261. case 'option' : 
  262. if ( ! $is_multidimensional ) { 
  263. add_filter( "pre_option_{$id_base}", array( $this, '_preview_filter' ) ); 
  264. } else { 
  265. if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) { 
  266. // Only add these filters once for this ID base. 
  267. add_filter( "option_{$id_base}", $multidimensional_filter ); 
  268. add_filter( "default_option_{$id_base}", $multidimensional_filter ); 
  269. self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'][ $this->id ] = $this; 
  270. break; 
  271. default : 
  272.  
  273. /** 
  274. * Fires when the WP_Customize_Setting::preview() method is called for settings 
  275. * not handled as theme_mods or options. 
  276. * The dynamic portion of the hook name, `$this->id`, refers to the setting ID. 
  277. * @since 3.4.0 
  278. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  279. */ 
  280. do_action( "customize_preview_{$this->id}", $this ); 
  281.  
  282. /** 
  283. * Fires when the WP_Customize_Setting::preview() method is called for settings 
  284. * not handled as theme_mods or options. 
  285. * The dynamic portion of the hook name, `$this->type`, refers to the setting type. 
  286. * @since 4.1.0 
  287. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  288. */ 
  289. do_action( "customize_preview_{$this->type}", $this ); 
  290.  
  291. $this->is_previewed = true; 
  292.  
  293. return true; 
  294.  
  295. /** 
  296. * Clear out the previewed-applied flag for a multidimensional-aggregated value whenever its post value is updated. 
  297. * This ensures that the new value will get sanitized and used the next time 
  298. * that `WP_Customize_Setting::_multidimensional_preview_filter()` 
  299. * is called for this setting. 
  300. * @since 4.4.0 
  301. * @access private 
  302. * @see WP_Customize_Manager::set_post_value() 
  303. * @see WP_Customize_Setting::_multidimensional_preview_filter() 
  304. */ 
  305. final public function _clear_aggregated_multidimensional_preview_applied_flag() { 
  306. unset( self::$aggregated_multidimensionals[ $this->type ][ $this->id_data['base'] ]['preview_applied_instances'][ $this->id ] ); 
  307.  
  308. /** 
  309. * Callback function to filter non-multidimensional theme mods and options. 
  310. * If switch_to_blog() was called after the preview() method, and the current 
  311. * site is now not the same site, then this method does a no-op and returns 
  312. * the original value. 
  313. * @since 3.4.0 
  314. * @param mixed $original Old value. 
  315. * @return mixed New or old value. 
  316. */ 
  317. public function _preview_filter( $original ) { 
  318. if ( ! $this->is_current_blog_previewed() ) { 
  319. return $original; 
  320.  
  321. $undefined = new stdClass(); // Symbol hack. 
  322. $post_value = $this->post_value( $undefined ); 
  323. if ( $undefined !== $post_value ) { 
  324. $value = $post_value; 
  325. } else { 
  326. /** 
  327. * Note that we don't use $original here because preview() will 
  328. * not add the filter in the first place if it has an initial value 
  329. * and there is no post value. 
  330. */ 
  331. $value = $this->default; 
  332. return $value; 
  333.  
  334. /** 
  335. * Callback function to filter multidimensional theme mods and options. 
  336. * For all multidimensional settings of a given type, the preview filter for 
  337. * the first setting previewed will be used to apply the values for the others. 
  338. * @since 4.4.0 
  339. * @access private 
  340. * @see WP_Customize_Setting::$aggregated_multidimensionals 
  341. * @param mixed $original Original root value. 
  342. * @return mixed New or old value. 
  343. */ 
  344. final public function _multidimensional_preview_filter( $original ) { 
  345. if ( ! $this->is_current_blog_previewed() ) { 
  346. return $original; 
  347.  
  348. $id_base = $this->id_data['base']; 
  349.  
  350. // If no settings have been previewed yet (which should not be the case, since $this is), just pass through the original value. 
  351. if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) { 
  352. return $original; 
  353.  
  354. foreach ( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] as $previewed_setting ) { 
  355. // Skip applying previewed value for any settings that have already been applied. 
  356. if ( ! empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['preview_applied_instances'][ $previewed_setting->id ] ) ) { 
  357. continue; 
  358.  
  359. // Do the replacements of the posted/default sub value into the root value. 
  360. $value = $previewed_setting->post_value( $previewed_setting->default ); 
  361. $root = self::$aggregated_multidimensionals[ $previewed_setting->type ][ $id_base ]['root_value']; 
  362. $root = $previewed_setting->multidimensional_replace( $root, $previewed_setting->id_data['keys'], $value ); 
  363. self::$aggregated_multidimensionals[ $previewed_setting->type ][ $id_base ]['root_value'] = $root; 
  364.  
  365. // Mark this setting having been applied so that it will be skipped when the filter is called again. 
  366. self::$aggregated_multidimensionals[ $previewed_setting->type ][ $id_base ]['preview_applied_instances'][ $previewed_setting->id ] = true; 
  367.  
  368. return self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value']; 
  369.  
  370. /** 
  371. * Checks user capabilities and theme supports, and then saves 
  372. * the value of the setting. 
  373. * @since 3.4.0 
  374. * @access public 
  375. * @return false|void False if cap check fails or value isn't set or is invalid. 
  376. */ 
  377. final public function save() { 
  378. $value = $this->post_value(); 
  379.  
  380. if ( ! $this->check_capabilities() || ! isset( $value ) ) { 
  381. return false; 
  382.  
  383. /** 
  384. * Fires when the WP_Customize_Setting::save() method is called. 
  385. * The dynamic portion of the hook name, `$this->id_data['base']` refers to 
  386. * the base slug of the setting name. 
  387. * @since 3.4.0 
  388. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  389. */ 
  390. do_action( 'customize_save_' . $this->id_data['base'], $this ); 
  391.  
  392. $this->update( $value ); 
  393.  
  394. /** 
  395. * Fetch and sanitize the $_POST value for the setting. 
  396. * @since 3.4.0 
  397. * @param mixed $default A default value which is used as a fallback. Default is null. 
  398. * @return mixed The default value on failure, otherwise the sanitized and validated value. 
  399. */ 
  400. final public function post_value( $default = null ) { 
  401. return $this->manager->post_value( $this, $default ); 
  402.  
  403. /** 
  404. * Sanitize an input. 
  405. * @since 3.4.0 
  406. * @param string|array $value The value to sanitize. 
  407. * @return string|array|null|WP_Error Sanitized value, or `null`/`WP_Error` if invalid. 
  408. */ 
  409. public function sanitize( $value ) { 
  410.  
  411. /** 
  412. * Filters a Customize setting value in un-slashed form. 
  413. * @since 3.4.0 
  414. * @param mixed $value Value of the setting. 
  415. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  416. */ 
  417. return apply_filters( "customize_sanitize_{$this->id}", $value, $this ); 
  418.  
  419. /** 
  420. * Validates an input. 
  421. * @since 4.6.0 
  422. * @access public 
  423. * @see WP_REST_Request::has_valid_params() 
  424. * @param mixed $value Value to validate. 
  425. * @return true|WP_Error True if the input was validated, otherwise WP_Error. 
  426. */ 
  427. public function validate( $value ) { 
  428. if ( is_wp_error( $value ) ) { 
  429. return $value; 
  430. if ( is_null( $value ) ) { 
  431. return new WP_Error( 'invalid_value', __( 'Invalid value.' ) ); 
  432.  
  433. $validity = new WP_Error(); 
  434.  
  435. /** 
  436. * Validates a Customize setting value. 
  437. * Plugins should amend the `$validity` object via its `WP_Error::add()` method. 
  438. * The dynamic portion of the hook name, `$this->ID`, refers to the setting ID. 
  439. * @since 4.6.0 
  440. * @param WP_Error $validity Filtered from `true` to `WP_Error` when invalid. 
  441. * @param mixed $value Value of the setting. 
  442. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  443. */ 
  444. $validity = apply_filters( "customize_validate_{$this->id}", $validity, $value, $this ); 
  445.  
  446. if ( is_wp_error( $validity ) && empty( $validity->errors ) ) { 
  447. $validity = true; 
  448. return $validity; 
  449.  
  450. /** 
  451. * Get the root value for a setting, especially for multidimensional ones. 
  452. * @since 4.4.0 
  453. * @access protected 
  454. * @param mixed $default Value to return if root does not exist. 
  455. * @return mixed 
  456. */ 
  457. protected function get_root_value( $default = null ) { 
  458. $id_base = $this->id_data['base']; 
  459. if ( 'option' === $this->type ) { 
  460. return get_option( $id_base, $default ); 
  461. } else if ( 'theme_mod' ) { 
  462. return get_theme_mod( $id_base, $default ); 
  463. } else { 
  464. /** 
  465. * Any WP_Customize_Setting subclass implementing aggregate multidimensional 
  466. * will need to override this method to obtain the data from the appropriate 
  467. * location. 
  468. */ 
  469. return $default; 
  470.  
  471. /** 
  472. * Set the root value for a setting, especially for multidimensional ones. 
  473. * @since 4.4.0 
  474. * @access protected 
  475. * @param mixed $value Value to set as root of multidimensional setting. 
  476. * @return bool Whether the multidimensional root was updated successfully. 
  477. */ 
  478. protected function set_root_value( $value ) { 
  479. $id_base = $this->id_data['base']; 
  480. if ( 'option' === $this->type ) { 
  481. $autoload = true; 
  482. if ( isset( self::$aggregated_multidimensionals[ $this->type ][ $this->id_data['base'] ]['autoload'] ) ) { 
  483. $autoload = self::$aggregated_multidimensionals[ $this->type ][ $this->id_data['base'] ]['autoload']; 
  484. return update_option( $id_base, $value, $autoload ); 
  485. } else if ( 'theme_mod' ) { 
  486. set_theme_mod( $id_base, $value ); 
  487. return true; 
  488. } else { 
  489. /** 
  490. * Any WP_Customize_Setting subclass implementing aggregate multidimensional 
  491. * will need to override this method to obtain the data from the appropriate 
  492. * location. 
  493. */ 
  494. return false; 
  495.  
  496. /** 
  497. * Save the value of the setting, using the related API. 
  498. * @since 3.4.0 
  499. * @param mixed $value The value to update. 
  500. * @return bool The result of saving the value. 
  501. */ 
  502. protected function update( $value ) { 
  503. $id_base = $this->id_data['base']; 
  504. if ( 'option' === $this->type || 'theme_mod' === $this->type ) { 
  505. if ( ! $this->is_multidimensional_aggregated ) { 
  506. return $this->set_root_value( $value ); 
  507. } else { 
  508. $root = self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value']; 
  509. $root = $this->multidimensional_replace( $root, $this->id_data['keys'], $value ); 
  510. self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value'] = $root; 
  511. return $this->set_root_value( $root ); 
  512. } else { 
  513. /** 
  514. * Fires when the WP_Customize_Setting::update() method is called for settings 
  515. * not handled as theme_mods or options. 
  516. * The dynamic portion of the hook name, `$this->type`, refers to the type of setting. 
  517. * @since 3.4.0 
  518. * @param mixed $value Value of the setting. 
  519. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  520. */ 
  521. do_action( "customize_update_{$this->type}", $value, $this ); 
  522.  
  523. return has_action( "customize_update_{$this->type}" ); 
  524.  
  525. /** 
  526. * Deprecated method. 
  527. * @since 3.4.0 
  528. * @deprecated 4.4.0 Deprecated in favor of update() method. 
  529. */ 
  530. protected function _update_theme_mod() { 
  531. _deprecated_function( __METHOD__, '4.4.0', __CLASS__ . '::update()' ); 
  532.  
  533. /** 
  534. * Deprecated method. 
  535. * @since 3.4.0 
  536. * @deprecated 4.4.0 Deprecated in favor of update() method. 
  537. */ 
  538. protected function _update_option() { 
  539. _deprecated_function( __METHOD__, '4.4.0', __CLASS__ . '::update()' ); 
  540.  
  541. /** 
  542. * Fetch the value of the setting. 
  543. * @since 3.4.0 
  544. * @return mixed The value. 
  545. */ 
  546. public function value() { 
  547. $id_base = $this->id_data['base']; 
  548. $is_core_type = ( 'option' === $this->type || 'theme_mod' === $this->type ); 
  549.  
  550. if ( ! $is_core_type && ! $this->is_multidimensional_aggregated ) { 
  551. $value = $this->get_root_value( $this->default ); 
  552.  
  553. /** 
  554. * Filters a Customize setting value not handled as a theme_mod or option. 
  555. * The dynamic portion of the hook name, `$id_base`, refers to 
  556. * the base slug of the setting name, initialized from `$this->id_data['base']`. 
  557. * For settings handled as theme_mods or options, see those corresponding 
  558. * functions for available hooks. 
  559. * @since 3.4.0 
  560. * @since 4.6.0 Added the `$this` setting instance as the second parameter. 
  561. * @param mixed $default The setting default value. Default empty. 
  562. * @param WP_Customize_Setting $this The setting instance. 
  563. */ 
  564. $value = apply_filters( "customize_value_{$id_base}", $value, $this ); 
  565. } elseif ( $this->is_multidimensional_aggregated ) { 
  566. $root_value = self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value']; 
  567. $value = $this->multidimensional_get( $root_value, $this->id_data['keys'], $this->default ); 
  568.  
  569. // Ensure that the post value is used if the setting is previewed, since preview filters aren't applying on cached $root_value. 
  570. if ( $this->is_previewed ) { 
  571. $value = $this->post_value( $value ); 
  572. } else { 
  573. $value = $this->get_root_value( $this->default ); 
  574. return $value; 
  575.  
  576. /** 
  577. * Sanitize the setting's value for use in JavaScript. 
  578. * @since 3.4.0 
  579. * @return mixed The requested escaped value. 
  580. */ 
  581. public function js_value() { 
  582.  
  583. /** 
  584. * Filters a Customize setting value for use in JavaScript. 
  585. * The dynamic portion of the hook name, `$this->id`, refers to the setting ID. 
  586. * @since 3.4.0 
  587. * @param mixed $value The setting value. 
  588. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  589. */ 
  590. $value = apply_filters( "customize_sanitize_js_{$this->id}", $this->value(), $this ); 
  591.  
  592. if ( is_string( $value ) ) 
  593. return html_entity_decode( $value, ENT_QUOTES, 'UTF-8'); 
  594.  
  595. return $value; 
  596.  
  597. /** 
  598. * Retrieves the data to export to the client via JSON. 
  599. * @since 4.6.0 
  600. * @access public 
  601. * @return array Array of parameters passed to JavaScript. 
  602. */ 
  603. public function json() { 
  604. return array( 
  605. 'value' => $this->js_value(),  
  606. 'transport' => $this->transport,  
  607. 'dirty' => $this->dirty,  
  608. 'type' => $this->type,  
  609. ); 
  610.  
  611. /** 
  612. * Validate user capabilities whether the theme supports the setting. 
  613. * @since 3.4.0 
  614. * @return bool False if theme doesn't support the setting or user can't change setting, otherwise true. 
  615. */ 
  616. final public function check_capabilities() { 
  617. if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) ) 
  618. return false; 
  619.  
  620. if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) ) 
  621. return false; 
  622.  
  623. return true; 
  624.  
  625. /** 
  626. * Multidimensional helper function. 
  627. * @since 3.4.0 
  628. * @param $root 
  629. * @param $keys 
  630. * @param bool $create Default is false. 
  631. * @return array|void Keys are 'root', 'node', and 'key'. 
  632. */ 
  633. final protected function multidimensional( &$root, $keys, $create = false ) { 
  634. if ( $create && empty( $root ) ) 
  635. $root = array(); 
  636.  
  637. if ( ! isset( $root ) || empty( $keys ) ) 
  638. return; 
  639.  
  640. $last = array_pop( $keys ); 
  641. $node = &$root; 
  642.  
  643. foreach ( $keys as $key ) { 
  644. if ( $create && ! isset( $node[ $key ] ) ) 
  645. $node[ $key ] = array(); 
  646.  
  647. if ( ! is_array( $node ) || ! isset( $node[ $key ] ) ) 
  648. return; 
  649.  
  650. $node = &$node[ $key ]; 
  651.  
  652. if ( $create ) { 
  653. if ( ! is_array( $node ) ) { 
  654. // account for an array overriding a string or object value 
  655. $node = array(); 
  656. if ( ! isset( $node[ $last ] ) ) { 
  657. $node[ $last ] = array(); 
  658.  
  659. if ( ! isset( $node[ $last ] ) ) 
  660. return; 
  661.  
  662. return array( 
  663. 'root' => &$root,  
  664. 'node' => &$node,  
  665. 'key' => $last,  
  666. ); 
  667.  
  668. /** 
  669. * Will attempt to replace a specific value in a multidimensional array. 
  670. * @since 3.4.0 
  671. * @param $root 
  672. * @param $keys 
  673. * @param mixed $value The value to update. 
  674. * @return mixed 
  675. */ 
  676. final protected function multidimensional_replace( $root, $keys, $value ) { 
  677. if ( ! isset( $value ) ) 
  678. return $root; 
  679. elseif ( empty( $keys ) ) // If there are no keys, we're replacing the root. 
  680. return $value; 
  681.  
  682. $result = $this->multidimensional( $root, $keys, true ); 
  683.  
  684. if ( isset( $result ) ) 
  685. $result['node'][ $result['key'] ] = $value; 
  686.  
  687. return $root; 
  688.  
  689. /** 
  690. * Will attempt to fetch a specific value from a multidimensional array. 
  691. * @since 3.4.0 
  692. * @param $root 
  693. * @param $keys 
  694. * @param mixed $default A default value which is used as a fallback. Default is null. 
  695. * @return mixed The requested value or the default value. 
  696. */ 
  697. final protected function multidimensional_get( $root, $keys, $default = null ) { 
  698. if ( empty( $keys ) ) // If there are no keys, test the root. 
  699. return isset( $root ) ? $root : $default; 
  700.  
  701. $result = $this->multidimensional( $root, $keys ); 
  702. return isset( $result ) ? $result['node'][ $result['key'] ] : $default; 
  703.  
  704. /** 
  705. * Will attempt to check if a specific value in a multidimensional array is set. 
  706. * @since 3.4.0 
  707. * @param $root 
  708. * @param $keys 
  709. * @return bool True if value is set, false if not. 
  710. */ 
  711. final protected function multidimensional_isset( $root, $keys ) { 
  712. $result = $this->multidimensional_get( $root, $keys ); 
  713. return isset( $result );