IntenseWebs/WordPress
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs: Improve phpdoc for WP_Customize_Manager, WP_Customize_Control, WP_Customize_Setting, and WP_Customize_Selective_Refresh.

Browse Source 
Props 4nickpick, sagarprajapati, ketuchetan, BharatKambariya, mrahmadawais, westonruter.
Fixes #39671.

Built from https://develop.svn.wordpress.org/trunk@40804


git-svn-id: http://core.svn.wordpress.org/trunk@40662 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Weston Ruter
2017-05-19 20:25:41 +00:00
parent 2c5e9a34b2
commit e8e5a71a85
5 changed files with 250 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
wp-includes/class-wp-customize-setting.php
View File

@@ -18,6 +18,9 @@
*/
class WP_Customize_Setting {
/**
* Customizer bootstrap instance.
*
* @since 3.4.0
* @access public
* @var WP_Customize_Manager
*/
@@ -26,12 +29,16 @@ class WP_Customize_Setting {
/**
* Unique string identifier for the setting.
*
* @since 3.4.0
* @access public
* @var string
*/
public $id;
/**
* Type of customize settings.
*
* @since 3.4.0
* @access public
* @var string
*/
@@ -40,27 +47,69 @@ class WP_Customize_Setting {
/**
* Capability required to edit this setting.
*
* @var string
* @since 3.4.0
* @access public
* @var string|array
*/
public $capability = 'edit_theme_options';
/**
* Feature a theme is required to support to enable this setting.
*
* @since 3.4.0
* @access public
* @var string
*/
public $theme_supports = '';
public $default = '';
public $transport = 'refresh';
public $theme_supports = '';
/**
* Server-side sanitization callback for the setting's value.
* The default value for the setting.
*
* @var callback
* @since 3.4.0
* @access public
* @var string
*/
public $default = '';
/**
* Options for rendering the live preview of changes in Theme Customizer.
*
* Set this value to 'postMessage' to enable a custom Javascript handler to render changes to this setting
* as opposed to reloading the whole page.
*
* @link https://developer.wordpress.org/themes/customize-api
*
* @since 3.4.0
* @access public
* @var string
*/
public $transport = 'refresh';
/**
* Server-side validation callback for the setting's value.
*
* @since 4.6.0
* @access public
* @var callable
*/
public $validate_callback = '';
/**
* Callback to filter a Customize setting value in un-slashed form.
*
* @since 3.4.0
* @access public
* @var callable
*/
public $sanitize_callback = '';
/**
* Callback to convert a Customize PHP setting value to a value that is JSON serializable.
*
* @since 3.4.0
* @access public
* @var string
*/
public $validate_callback = '';
public $sanitize_callback = '';
public $sanitize_js_callback = '';
/**
@@ -78,6 +127,10 @@ class WP_Customize_Setting {
public $dirty = false;
/**
* ID Data.
*
* @since 3.4.0
* @access protected
* @var array
*/
protected $id_data = array();
@@ -95,9 +148,9 @@ class WP_Customize_Setting {
* Cache of multidimensional values to improve performance.
*
* @since 4.4.0
* @static
* @access protected
* @var array
* @static
*/
protected static $aggregated_multidimensionals = array();
@@ -168,7 +221,6 @@ class WP_Customize_Setting {
* Get parsed ID data for multidimensional setting.
*
* @since 4.4.0
* @access public
*
* @return array {
* ID data for multidimensional setting.
@@ -188,7 +240,6 @@ class WP_Customize_Setting {
* calls get combined into one call, greatly improving performance.
*
* @since 4.4.0
* @access protected
*/
protected function aggregate_multidimensional() {
$id_base = $this->id_data['base'];
@@ -216,7 +267,6 @@ class WP_Customize_Setting {
* This is intended only for use by unit tests.
*
* @since 4.5.0
* @access public
* @ignore
*/
static public function reset_aggregated_multidimensionals() {
@@ -236,7 +286,6 @@ class WP_Customize_Setting {
* Return true if the current site is not the same as the previewed site.
*
* @since 4.2.0
* @access public
*
* @return bool If preview() has been called.
*/
@@ -252,6 +301,7 @@ class WP_Customize_Setting {
*
* @see WP_Customize_Setting::preview()
* @since 4.1.1
* @access protected
* @var mixed
*/
protected $_original_value;
@@ -265,7 +315,6 @@ class WP_Customize_Setting {
*
* @since 3.4.0
* @since 4.4.0 Added boolean return value.
* @access public
*
* @return bool False when preview short-circuits due no change needing to be previewed.
*/
@@ -379,7 +428,7 @@ class WP_Customize_Setting {
* is called for this setting.
*
* @since 4.4.0
* @access private
*
* @see WP_Customize_Manager::set_post_value()
* @see WP_Customize_Setting::_multidimensional_preview_filter()
*/
@@ -426,7 +475,6 @@ class WP_Customize_Setting {
* the first setting previewed will be used to apply the values for the others.
*
* @since 4.4.0
* @access private
*
* @see WP_Customize_Setting::$aggregated_multidimensionals
* @param mixed $original Original root value.
@@ -469,8 +517,6 @@ class WP_Customize_Setting {
*
* @since 3.4.0
*
* @access public
*
* @return false|void False if cap check fails or value isn't set or is invalid.
*/
final public function save() {
@@ -536,7 +582,6 @@ class WP_Customize_Setting {
* Validates an input.
*
* @since 4.6.0
* @access public
*
* @see WP_REST_Request::has_valid_params()
*
@@ -578,7 +623,6 @@ class WP_Customize_Setting {
* Get the root value for a setting, especially for multidimensional ones.
*
* @since 4.4.0
* @access protected
*
* @param mixed $default Value to return if root does not exist.
* @return mixed
@@ -603,7 +647,6 @@ class WP_Customize_Setting {
* Set the root value for a setting, especially for multidimensional ones.
*
* @since 4.4.0
* @access protected
*
* @param mixed $value Value to set as root of multidimensional setting.
* @return bool Whether the multidimensional root was updated successfully.
@@ -770,7 +813,6 @@ class WP_Customize_Setting {
* Retrieves the data to export to the client via JSON.
*
* @since 4.6.0
* @access public
*
* @return array Array of parameters passed to JavaScript.
*/
@@ -907,17 +949,27 @@ class WP_Customize_Setting {
}
}
/** WP_Customize_Filter_Setting class */
/**
* WP_Customize_Filter_Setting class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-filter-setting.php' );
/** WP_Customize_Header_Image_Setting class */
/**
* WP_Customize_Header_Image_Setting class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-header-image-setting.php' );
/** WP_Customize_Background_Image_Setting class */
/**
* WP_Customize_Background_Image_Setting class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-background-image-setting.php' );
/** WP_Customize_Nav_Menu_Item_Setting class */
/**
* WP_Customize_Nav_Menu_Item_Setting class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-item-setting.php' );
/** WP_Customize_Nav_Menu_Setting class */
/**
* WP_Customize_Nav_Menu_Setting class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-setting.php' );