diff --git wp-includes/class-wp-customize-control.php wp-includes/class-wp-customize-control.php index 07c6dcfce..3851fc0aa 100644 --- wp-includes/class-wp-customize-control.php +++ wp-includes/class-wp-customize-control.php @@ -77,24 +77,32 @@ class WP_Customize_Control { public $capability; /** + * Order priority to load the control. + * * @access public * @var int */ public $priority = 10; /** + * Section the control belongs to. + * * @access public * @var string */ public $section = ''; /** + * Label for the control. + * * @access public * @var string */ public $label = ''; /** + * Description for the control. + * * @access public * @var string */ @@ -102,6 +110,7 @@ class WP_Customize_Control { /** * @todo: Remove choices + * List of choices for 'radio' or 'select' type controls, where values are the keys, and labels are the values. * * @access public * @var array @@ -109,6 +118,10 @@ class WP_Customize_Control { 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. + * * @access public * @var array */ diff --git wp-includes/class-wp-customize-manager.php wp-includes/class-wp-customize-manager.php index 229a2484b..1161a5eb0 100644 --- wp-includes/class-wp-customize-manager.php +++ wp-includes/class-wp-customize-manager.php @@ -2793,8 +2793,24 @@ final class WP_Customize_Manager { * @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. + * @see https://codex.wordpress.org/Theme_Customization_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 filter a Customize setting value for use in Javascript. + * @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() ) { @@ -2911,7 +2927,18 @@ final class WP_Customize_Manager { * @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. */ @@ -3000,7 +3027,20 @@ 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. */ @@ -3076,8 +3116,27 @@ 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() ) { diff --git wp-includes/class-wp-customize-setting.php wp-includes/class-wp-customize-setting.php index 83a5b76d6..46e3c5ab3 100644 --- wp-includes/class-wp-customize-setting.php +++ wp-includes/class-wp-customize-setting.php @@ -40,7 +40,7 @@ class WP_Customize_Setting { /** * Capability required to edit this setting. * - * @var string + * @var string|array */ public $capability = 'edit_theme_options'; @@ -51,16 +51,47 @@ class WP_Customize_Setting { * @var string */ public $theme_supports = ''; + + /** + * The default value for the setting. + * + * @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. + * + * @see https://codex.wordpress.org/Theme_Customization_API + * + * @access public + * @var string + */ public $transport = 'refresh'; /** - * Server-side sanitization callback for the setting's value. + * Server-side validation callback for the setting's value. * - * @var callback + * @var callable */ public $validate_callback = ''; + + /** + * Callback to filter a Customize setting value in un-slashed form. + * + * @var callable + */ public $sanitize_callback = ''; + + /** + * Callback to filter a Customize setting value for use in Javascript. + * + * @var callable + */ public $sanitize_js_callback = ''; /** diff --git wp-includes/customize/class-wp-customize-selective-refresh.php wp-includes/customize/class-wp-customize-selective-refresh.php index 23d5a9488..32c201d8e 100644 --- wp-includes/customize/class-wp-customize-selective-refresh.php +++ wp-includes/customize/class-wp-customize-selective-refresh.php @@ -91,7 +91,30 @@ final class WP_Customize_Selective_Refresh { * @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. Default 'default'. + * @type string $selector The jQuery selector to find the container element for the partial. + * @type array $settings IDs for settings tied to the partial. If undefined, `$id` will be used. + * IDs in the array correspond to the ID of a registered instance + * of `WP_Customize_Setting` + * @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. Default false. + * @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. Default true. + * } + * * @return WP_Customize_Partial The instance of the panel that was added. */ public function add_partial( $id, $args = array() ) {