diff --git src/wp-includes/class-wp-customize-control.php src/wp-includes/class-wp-customize-control.php index 07c6dcfce1..267989da5e 100644 --- src/wp-includes/class-wp-customize-control.php +++ src/wp-includes/class-wp-customize-control.php @@ -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' ); diff --git src/wp-includes/class-wp-customize-manager.php src/wp-includes/class-wp-customize-manager.php index 669ce05c80..62d587bf6a 100644 --- src/wp-includes/class-wp-customize-manager.php +++ src/wp-includes/class-wp-customize-manager.php @@ -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. */ diff --git src/wp-includes/class-wp-customize-setting.php src/wp-includes/class-wp-customize-setting.php index 83a5b76d61..8fab457ce3 100644 --- src/wp-includes/class-wp-customize-setting.php +++ src/wp-includes/class-wp-customize-setting.php @@ -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 = ''; + + /** + * The default value for the setting. + * + * @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 $theme_supports = ''; - public $default = ''; - public $transport = 'refresh'; + 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 = ''; /** - * Server-side sanitization callback for the setting's value. + * Callback to convert a Customize PHP setting value to a value that is JSON serializable. * - * @var callback + * @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' ); diff --git src/wp-includes/customize/class-wp-customize-selective-refresh.php src/wp-includes/customize/class-wp-customize-selective-refresh.php index 6c04a73698..a1811299d8 100644 --- src/wp-includes/customize/class-wp-customize-selective-refresh.php +++ src/wp-includes/customize/class-wp-customize-selective-refresh.php @@ -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() ) {