WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
wp-includes/class-wp-customize-control.php
View File

@ -37,12 +37,18 @@ class WP_Customize_Control {
public $instance_number;
/**
* Customizer manager.
*
* @since 3.4.0
* @access public
* @var WP_Customize_Manager
*/
public $manager;
/**
* Control ID.
*
* @since 3.4.0
* @access public
* @var string
*/
@ -51,6 +57,7 @@ class WP_Customize_Control {
/**
* All settings tied to the control.
*
* @since 3.4.0
* @access public
* @var array
*/
@ -59,6 +66,7 @@ class WP_Customize_Control {
/**
* The primary setting for the control (if there is one).
*
* @since 3.4.0
* @access public
* @var string
*/
@ -77,38 +85,56 @@ class WP_Customize_Control {
public $capability;
/**
* Order priority to load the control in Customizer.
*
* @since 3.4.0
* @access public
* @var int
*/
public $priority = 10;
/**
* Section the control belongs to.
*
* @since 3.4.0
* @access public
* @var string
*/
public $section = '';
/**
* Label for the control.
*
* @since 3.4.0
* @access public
* @var string
*/
public $label = '';
/**
* Description for the control.
*
* @since 4.0.0
* @access public
* @var string
*/
public $description = '';
/**
* @todo: Remove choices
* List of choices for 'radio' or 'select' type controls, where values are the keys, and labels are the values.
*
* @since 3.4.0
* @access public
* @var array
*/
public $choices = array();
/**
* List of custom input attributes for control output, where attribute names are the keys and values are the values.
*
* Not used for 'checkbox', 'radio', 'select', 'textarea', or 'dropdown-pages' control types.
*
* @since 4.0.0
* @access public
* @var array
*/
@ -125,12 +151,16 @@ class WP_Customize_Control {
/**
* @deprecated It is better to just call the json() method
* @since 3.4.0
* @access public
* @var array
*/
public $json = array();
/**
* Control's Type.
*
* @since 3.4.0
* @access public
* @var string
*/
@ -235,7 +265,6 @@ class WP_Customize_Control {
* Check whether control is active to current Customizer preview.
*
* @since 4.0.0
* @access public
*
* @return bool Whether the control is active to the current preview.
*/
@ -263,7 +292,6 @@ class WP_Customize_Control {
* provide an 'active_callback' argument to the constructor.
*
* @since 4.0.0
* @access public
*
* @return true Always true.
*/
@ -446,7 +474,6 @@ class WP_Customize_Control {
* Render the custom attributes for the control's input element.
*
* @since 4.0.0
* @access public
*/
public function input_attrs() {
foreach ( $this->input_attrs as $attr => $value ) {
@ -648,56 +675,92 @@ class WP_Customize_Control {
}
/** WP_Customize_Color_Control class */
/**
* WP_Customize_Color_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-color-control.php' );
/** WP_Customize_Media_Control class */
/**
* WP_Customize_Media_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-media-control.php' );
/** WP_Customize_Upload_Control class */
/**
* WP_Customize_Upload_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-upload-control.php' );
/** WP_Customize_Image_Control class */
/**
* WP_Customize_Image_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-image-control.php' );
/** WP_Customize_Background_Image_Control class */
/**
* WP_Customize_Background_Image_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-background-image-control.php' );
/** WP_Customize_Background_Position_Control class */
/**
* WP_Customize_Background_Position_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-background-position-control.php' );
/** WP_Customize_Cropped_Image_Control class */
/**
* WP_Customize_Cropped_Image_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-cropped-image-control.php' );
/** WP_Customize_Site_Icon_Control class */
/**
* WP_Customize_Site_Icon_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-site-icon-control.php' );
/** WP_Customize_Header_Image_Control class */
/**
* WP_Customize_Header_Image_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-header-image-control.php' );
/** WP_Customize_Theme_Control class */
/**
* WP_Customize_Theme_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-theme-control.php' );
/** WP_Widget_Area_Customize_Control class */
/**
* WP_Widget_Area_Customize_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-widget-area-customize-control.php' );
/** WP_Widget_Form_Customize_Control class */
/**
* WP_Widget_Form_Customize_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-widget-form-customize-control.php' );
/** WP_Customize_Nav_Menu_Control class */
/**
* WP_Customize_Nav_Menu_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-control.php' );
/** WP_Customize_Nav_Menu_Item_Control class */
/**
* WP_Customize_Nav_Menu_Item_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-item-control.php' );
/** WP_Customize_Nav_Menu_Location_Control class */
/**
* WP_Customize_Nav_Menu_Location_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-location-control.php' );
/** WP_Customize_Nav_Menu_Name_Control class */
/**
* WP_Customize_Nav_Menu_Name_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-name-control.php' );
/** WP_Customize_Nav_Menu_Auto_Add_Control class */
/**
* WP_Customize_Nav_Menu_Auto_Add_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-auto-add-control.php' );
/** WP_Customize_New_Menu_Control class */
/**
* WP_Customize_New_Menu_Control class.
*/
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-new-menu-control.php' );

78
wp-includes/class-wp-customize-manager.php
View File

@ -2810,11 +2810,27 @@ final class WP_Customize_Manager {
*
* @since 3.4.0
* @since 4.5.0 Return added WP_Customize_Setting instance.
* @access public
*
* @param WP_Customize_Setting|string $id Customize Setting object, or ID.
* @param array $args Setting arguments; passed to WP_Customize_Setting
* constructor.
* @param array $args {
* Optional. Array of properties for the new WP_Customize_Setting. Default empty array.
*
* @type string $type Type of the setting. Default 'theme_mod'.
* Default 160.
* @type string $capability Capability required for the setting. Default 'edit_theme_options'
* @type string|array $theme_supports Theme features required to support the panel. Default is none.
* @type string $default Default value for the setting. Default is empty string.
* @type string $transport Options for rendering the live preview of changes in Theme Customizer.
* Using 'refresh' makes the change visible by reloading the whole preview.
* Using 'postMessage' allows a custom JavaScript to handle live changes.
* @link https://developer.wordpress.org/themes/customize-api
* Default is 'refresh'
* @type callable $validate_callback Server-side validation callback for the setting's value.
* @type callable $sanitize_callback Callback to filter a Customize setting value in un-slashed form.
* @type callable $sanitize_js_callback Callback to convert a Customize PHP setting value to a value that is
* JSON serializable.
* @type bool $dirty Whether or not the setting is initially dirty when created.
* }
* @return WP_Customize_Setting The instance of the setting that was added.
*/
public function add_setting( $id, $args = array() ) {
@ -2928,11 +2944,19 @@ final class WP_Customize_Manager {
*
* @since 4.0.0
* @since 4.5.0 Return added WP_Customize_Panel instance.
* @access public
*
* @param WP_Customize_Panel|string $id Customize Panel object, or Panel ID.
* @param array $args Optional. Panel arguments. Default empty array.
*
* @param array $args {
* Optional. Array of properties for the new Panel object. Default empty array.
* @type int $priority Priority of the panel, defining the display order of panels and sections.
* Default 160.
* @type string $capability Capability required for the panel. Default `edit_theme_options`
* @type string|array $theme_supports Theme features required to support the panel.
* @type string $title Title of the panel to show in UI.
* @type string $description Description to show in the UI.
* @type string $type Type of the panel.
* @type callable $active_callback Active callback.
* }
* @return WP_Customize_Panel The instance of the panel that was added.
*/
public function add_panel( $id, $args = array() ) {
@ -3020,8 +3044,19 @@ final class WP_Customize_Manager {
* @access public
*
* @param WP_Customize_Section|string $id Customize Section object, or Section ID.
* @param array $args Section arguments.
*
* @param array $args {
* Optional. Array of properties for the new Panel object. Default empty array.
* @type int $priority Priority of the panel, defining the display order of panels and sections.
* Default 160.
* @type string $panel Priority of the panel, defining the display order of panels and sections.
* @type string $capability Capability required for the panel. Default 'edit_theme_options'
* @type string|array $theme_supports Theme features required to support the panel.
* @type string $title Title of the panel to show in UI.
* @type string $description Description to show in the UI.
* @type string $type Type of the panel.
* @type callable $active_callback Active callback.
* @type bool $description_hidden Hide the description behind a help icon, instead of . Default false.
* }
* @return WP_Customize_Section The instance of the section that was added.
*/
public function add_section( $id, $args = array() ) {
@ -3096,8 +3131,26 @@ final class WP_Customize_Manager {
* @access public
*
* @param WP_Customize_Control|string $id Customize Control object, or ID.
* @param array $args Control arguments; passed to WP_Customize_Control
* constructor.
* @param array $args {
* Optional. Array of properties for the new Control object. Default empty array.
*
* @type array $settings All settings tied to the control. If undefined, defaults to `$setting`.
* IDs in the array correspond to the ID of a registered `WP_Customize_Setting`.
* @type string $setting The primary setting for the control (if there is one). Default is 'default'.
* @type string $capability Capability required to use this control. Normally derived from `$settings`.
* @type int $priority Order priority to load the control. Default 10.
* @type string $section The section this control belongs to. Default empty.
* @type string $label Label for the control. Default empty.
* @type string $description Description for the control. Default empty.
* @type array $choices List of choices for 'radio' or 'select' type controls, where values
* are the keys, and labels are the values. Default empty array.
* @type array $input_attrs List of custom input attributes for control output, where attribute
* names are the keys and values are the values. Default empty array.
* @type bool $allow_addition Show UI for adding new content, currently only used for the
* dropdown-pages control. Default false.
* @type string $type The type of the control. Default 'text'.
* @type callback $active_callback Active callback.
* }
* @return WP_Customize_Control The instance of the control that was added.
*/
public function add_control( $id, $args = array() ) {
@ -3496,6 +3549,7 @@ final class WP_Customize_Manager {
* Get nonces for the Customizer.
*
* @since 4.5.0
*
* @return array Nonces.
*/
public function get_nonces() {
@ -3636,7 +3690,6 @@ final class WP_Customize_Manager {
/**
* Returns a list of devices to allow previewing.
*
* @access public
* @since 4.5.0
*
* @return array List of devices with labels and default setting.
@ -4188,7 +4241,6 @@ final class WP_Customize_Manager {
*
* Used as active callback for static front page section and controls.
*
* @access private
* @since 4.7.0
*
* @returns bool Whether there are published (or to be published) pages.
@ -4245,7 +4297,6 @@ final class WP_Customize_Manager {
* Callback for validating a background setting value.
*
* @since 4.7.0
* @access private
*
* @param string $value Repeat value.
* @param WP_Customize_Setting $setting Setting.
@ -4379,7 +4430,6 @@ final class WP_Customize_Manager {
* @see WP_Customize_Manager::register_controls()
*
* @since 4.5.0
* @access private
*
* @return string Custom logo.
*/

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' );

23
wp-includes/customize/class-wp-customize-selective-refresh.php
View File

@ -88,10 +88,29 @@ final class WP_Customize_Selective_Refresh {
* Adds a partial.
*
* @since 4.5.0
* @access public
*
* @param WP_Customize_Partial|string $id Customize Partial object, or Panel ID.
* @param array $args Optional. Partial arguments. Default empty array.
* @param array $args {
* Optional. Array of properties for the new Partials object. Default empty array.
*
* @type string $type Type of the partial to be created.
* @type string $selector The jQuery selector to find the container element for the partial, that is, a partial's placement.
* @type array $settings IDs for settings tied to the partial.
* @type string $primary_setting The ID for the setting that this partial is primarily responsible for
* rendering. If not supplied, it will default to the ID of the first setting.
* @type string $capability Capability required to edit this partial.
* Normally this is empty and the capability is derived from the capabilities
* of the associated `$settings`.
* @type callable $render_callback Render callback.
* Callback is called with one argument, the instance of WP_Customize_Partial.
* The callback can either echo the partial or return the partial as a string,
* or return false if error.
* @type bool $container_inclusive Whether the container element is included in the partial, or if only
* the contents are rendered.
* @type bool $fallback_refresh Whether to refresh the entire preview in case a partial cannot be refreshed.
* A partial render is considered a failure if the render_callback returns
* false.
* }
* @return WP_Customize_Partial The instance of the panel that was added.
*/
public function add_partial( $id, $args = array() ) {

2
wp-includes/version.php
View File

@ -4,7 +4,7 @@
*
* @global string $wp_version
*/
$wp_version = '4.8-beta1-40803';
$wp_version = '4.8-beta1-40804';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.