From f31ac162f585cac28d281d0fb047cd0f2070668b Mon Sep 17 00:00:00 2001 From: Andrew Nacin Date: Tue, 4 Mar 2014 20:21:14 +0000 Subject: [PATCH] Update the Customizer API inline docs. props ericlewis. fixes #27065. Built from https://develop.svn.wordpress.org/trunk@27398 git-svn-id: http://core.svn.wordpress.org/trunk@27246 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/customize.php | 7 +- wp-includes/class-wp-customize-control.php | 27 +++---- wp-includes/class-wp-customize-manager.php | 94 +++++++++++++++------- wp-includes/class-wp-customize-section.php | 50 ++++++++++-- wp-includes/class-wp-customize-setting.php | 76 +++++++++++++---- 5 files changed, 190 insertions(+), 64 deletions(-) diff --git a/wp-admin/customize.php b/wp-admin/customize.php index b247b19d28..0a693669bd 100644 --- a/wp-admin/customize.php +++ b/wp-admin/customize.php @@ -1,6 +1,6 @@ 1 ), wp_login_url() ); + // Prepare customizer settings to pass to Javascript. $settings = array( 'theme' => array( 'stylesheet' => $wp_customize->get_stylesheet(), @@ -227,6 +230,7 @@ do_action( 'customize_controls_print_scripts' ); ), ); + // Prepare Customize Setting objects to pass to Javascript. foreach ( $wp_customize->settings() as $id => $setting ) { $settings['settings'][ $id ] = array( 'value' => $setting->js_value(), @@ -234,6 +238,7 @@ do_action( 'customize_controls_print_scripts' ); ); } + // Prepare Customize Control objects to pass to Javascript. foreach ( $wp_customize->controls() as $id => $control ) { $control->to_json(); $settings['controls'][ $id ] = $control->json; diff --git a/wp-includes/class-wp-customize-control.php b/wp-includes/class-wp-customize-control.php index 1524666684..d714c03c4d 100644 --- a/wp-includes/class-wp-customize-control.php +++ b/wp-includes/class-wp-customize-control.php @@ -39,19 +39,19 @@ class WP_Customize_Control { * @access public * @var int */ - public $priority = 10; + public $priority = 10; /** * @access public * @var string */ - public $section = ''; + public $section = ''; /** * @access public * @var string */ - public $label = ''; + public $label = ''; /** * @todo: Remove choices @@ -59,7 +59,7 @@ class WP_Customize_Control { * @access public * @var array */ - public $choices = array(); + public $choices = array(); /** * @access public @@ -77,6 +77,8 @@ class WP_Customize_Control { /** * Constructor. * + * Supplied $args override class property defaults. + * * If $args['settings'] is not defined, use the $id as the setting ID. * * @since 3.4.0 @@ -95,7 +97,6 @@ class WP_Customize_Control { $this->manager = $manager; $this->id = $id; - // Process settings. if ( empty( $this->settings ) ) $this->settings = $id; @@ -185,7 +186,7 @@ class WP_Customize_Control { } /** - * Render the control. Renders the control wrapper, then calls $this->render_content(). + * Renders the control wrapper and calls $this->render_content() for the internals. * * @since 3.4.0 */ @@ -199,7 +200,7 @@ class WP_Customize_Control { } /** - * Get the data link parameter for a setting. + * Get the data link attribute for a setting. * * @since 3.4.0 * @@ -214,7 +215,7 @@ class WP_Customize_Control { } /** - * Render the data link parameter for a setting + * Render the data link attribute for the control's input element. * * @since 3.4.0 * @uses WP_Customize_Control::get_link() @@ -228,7 +229,9 @@ class WP_Customize_Control { /** * Render the control's content. * - * Allows the content to be overriden without having to rewrite the wrapper. + * Allows the content to be overriden without having to rewrite the wrapper in $this->render(). + * + * Supports basic input types `text`, `checkbox`, `radio`, `select` and `dropdown-pages`. * * @since 3.4.0 */ @@ -331,8 +334,6 @@ class WP_Customize_Color_Control extends WP_Customize_Control { /** * Constructor. * - * If $args['settings'] is not defined, use the $id as the setting ID. - * * @since 3.4.0 * @uses WP_Customize_Control::__construct() * @@ -346,7 +347,7 @@ class WP_Customize_Color_Control extends WP_Customize_Control { } /** - * Enqueue control related scripts/styles. + * Enqueue scripts/styles for the color picker. * * @since 3.4.0 */ @@ -467,8 +468,6 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control { /** * Constructor. * - * If $args['settings'] is not defined, use the $id as the setting ID. - * * @since 3.4.0 * @uses WP_Customize_Upload_Control::__construct() * diff --git a/wp-includes/class-wp-customize-manager.php b/wp-includes/class-wp-customize-manager.php index cad9f1351c..d68ff91cfd 100644 --- a/wp-includes/class-wp-customize-manager.php +++ b/wp-includes/class-wp-customize-manager.php @@ -2,14 +2,39 @@ /** * Customize Manager. * + * Bootstraps the Customize experience on the server-side. + * + * Sets up the theme-switching process if a theme other than the active one is + * being previewed and customized. + * + * Serves as a factory for Customize Controls and Settings, and + * instantiates default Customize Controls and Settings. + * * @package WordPress * @subpackage Customize * @since 3.4.0 */ final class WP_Customize_Manager { + /** + * An instance of the theme that is being customized. + * + * @var WP_Theme + */ protected $theme; + + /** + * The directory name of the previously active theme (within the theme_root). + * + * @var string + */ protected $original_stylesheet; + /** + * Whether filters have been set to change the active theme to the theme being + * customized. + * + * @var boolean + */ protected $previewing = false; protected $settings = array(); @@ -20,6 +45,11 @@ final class WP_Customize_Manager { protected $customized; + /** + * $_POST values for Customize Settings. + * + * @var array + */ private $_post_values; /** @@ -127,17 +157,21 @@ final class WP_Customize_Manager { // Once the theme is loaded, we'll validate it. add_action( 'after_setup_theme', array( $this, 'after_setup_theme' ) ); } else { + // If the requested theme is not the active theme and the user doesn't have the + // switch_themes cap, bail. if ( ! current_user_can( 'switch_themes' ) ) $this->wp_die( -1 ); - // If the theme isn't active, you can't preview it if it is not allowed or has errors. + // If the theme has errors while loading, bail. if ( $this->theme()->errors() ) $this->wp_die( -1 ); + // If the theme isn't allowed per multisite settings, bail. if ( ! $this->theme()->is_allowed() ) $this->wp_die( -1 ); } + // All good, let's do some internal business to preview the theme. $this->start_previewing_theme(); } @@ -154,9 +188,7 @@ final class WP_Customize_Manager { } /** - * Start previewing the selected theme. - * - * Adds filters to change the current theme. + * Start previewing the selected theme by adding filters to change the current theme. * * @since 3.4.0 */ @@ -300,12 +332,12 @@ final class WP_Customize_Manager { } /** - * Decode the $_POST attribute used to override the WP_Customize_Setting values. + * Decode the $_POST['customized'] values for a specific Customize Setting. * * @since 3.4.0 * * @param mixed $setting A WP_Customize_Setting derived object - * @return string Sanitized attribute + * @return string $post_value Sanitized value */ public function post_value( $setting ) { if ( ! isset( $this->_post_values ) ) { @@ -487,7 +519,7 @@ final class WP_Customize_Manager { } /** - * Switch the theme and trigger the save action of each setting. + * Switch the theme and trigger the save() method on each setting. * * @since 3.4.0 */ @@ -522,9 +554,9 @@ final class WP_Customize_Manager { * * @since 3.4.0 * - * @param string $id A specific ID of the setting. Can be a - * theme mod or option name. - * @param array $args Setting arguments. + * @param WP_Customize_Setting|string $id Customize Setting object, or ID. + * @param array $args Setting arguments; passed to WP_Customize_Setting + * constructor. */ public function add_setting( $id, $args = array() ) { if ( is_a( $id, 'WP_Customize_Setting' ) ) @@ -540,8 +572,8 @@ final class WP_Customize_Manager { * * @since 3.4.0 * - * @param string $id A specific ID of the setting. - * @return object The settings object. + * @param string $id Customize Setting ID. + * @return WP_Customize_Setting */ public function get_setting( $id ) { if ( isset( $this->settings[ $id ] ) ) @@ -553,7 +585,7 @@ final class WP_Customize_Manager { * * @since 3.4.0 * - * @param string $id A specific ID of the setting. + * @param string $id Customize Setting ID. */ public function remove_setting( $id ) { unset( $this->settings[ $id ] ); @@ -564,8 +596,8 @@ final class WP_Customize_Manager { * * @since 3.4.0 * - * @param string $id A specific ID of the section. - * @param array $args Section arguments. + * @param WP_Customize_Section|string $id Customize Section object, or Section ID. + * @param array $args Section arguments. */ public function add_section( $id, $args = array() ) { if ( is_a( $id, 'WP_Customize_Section' ) ) @@ -581,8 +613,8 @@ final class WP_Customize_Manager { * * @since 3.4.0 * - * @param string $id A specific ID of the section. - * @return object The section object. + * @param string $id Section ID. + * @return WP_Customize_Section */ public function get_section( $id ) { if ( isset( $this->sections[ $id ] ) ) @@ -594,7 +626,7 @@ final class WP_Customize_Manager { * * @since 3.4.0 * - * @param string $id A specific ID of the section. + * @param string $id Section ID. */ public function remove_section( $id ) { unset( $this->sections[ $id ] ); @@ -605,8 +637,9 @@ final class WP_Customize_Manager { * * @since 3.4.0 * - * @param string $id A specific ID of the control. - * @param array $args Setting arguments. + * @param WP_Customize_Control|string $id Customize Control object, or ID. + * @param array $args Control arguments; passed to WP_Customize_Control + * constructor. */ public function add_control( $id, $args = array() ) { if ( is_a( $id, 'WP_Customize_Control' ) ) @@ -622,8 +655,8 @@ final class WP_Customize_Manager { * * @since 3.4.0 * - * @param string $id A specific ID of the control. - * @return object The settings object. + * @param string $id ID of the control. + * @return WP_Customize_Control $control The control object. */ public function get_control( $id ) { if ( isset( $this->controls[ $id ] ) ) @@ -631,11 +664,11 @@ final class WP_Customize_Manager { } /** - * Remove a customize setting. + * Remove a customize control. * * @since 3.4.0 * - * @param string $id A specific ID of the control. + * @param string $id ID of the control. */ public function remove_control( $id ) { unset( $this->controls[ $id ] ); @@ -662,11 +695,13 @@ final class WP_Customize_Manager { /** * Prepare settings and sections. * + * For each, check if required related components exist, + * whether the user has the necessary capabilities, + * and sort by priority. + * * @since 3.4.0 */ public function prepare_controls() { - // Prepare controls - // Reversing makes uasort sort by time added when conflicts occur. $this->controls = array_reverse( $this->controls ); $controls = array(); @@ -680,7 +715,8 @@ final class WP_Customize_Manager { } $this->controls = $controls; - // Prepare sections + // Prepare sections. + // Reversing makes uasort sort by time added when conflicts occur. $this->sections = array_reverse( $this->sections ); uasort( $this->sections, array( $this, '_cmp_priority' ) ); $sections = array(); @@ -995,10 +1031,10 @@ final class WP_Customize_Manager { }; /** - * Validates a hex color. + * Sanitizes a hex color. * * Returns either '', a 3 or 6 digit hex color (with #), or null. - * For validating values without a #, see sanitize_hex_color_no_hash(). + * For sanitizing values without a #, see sanitize_hex_color_no_hash(). * * @since 3.4.0 * diff --git a/wp-includes/class-wp-customize-section.php b/wp-includes/class-wp-customize-section.php index f53ae9d670..3775b8e719 100644 --- a/wp-includes/class-wp-customize-section.php +++ b/wp-includes/class-wp-customize-section.php @@ -2,28 +2,67 @@ /** * Customize Section Class. * + * A UI container for controls, managed by the WP_Customize_Manager. + * * @package WordPress * @subpackage Customize * @since 3.4.0 */ class WP_Customize_Section { + /** + * @access public + * + * @var WP_Customize_Manager + */ public $manager; + + /** + * Unique identifier. + * + * @var string + */ public $id; + + /** + * Priority of the section which informs load order of sections. + * + * @var integer + */ public $priority = 10; + + /** + * Capability required for the section. + * + * @var string + */ public $capability = 'edit_theme_options'; public $theme_supports = ''; + + /** + * Title of the section to show in UI. + * + * @var string + */ public $title = ''; + + /** + * Description to show in the UI. + * + * @var string + */ public $description = ''; public $controls; /** * Constructor. * + * Any supplied $args override class property defaults. + * * @since 3.4.0 * * @param WP_Customize_Manager $manager - * @param string $id An specific ID of the section. - * @param array $args Section arguments. + * @param string $id An specific ID of the section. + * @param array $args Section arguments. */ function __construct( $manager, $id, $args = array() ) { $keys = array_keys( get_class_vars( __CLASS__ ) ); @@ -41,7 +80,8 @@ class WP_Customize_Section { } /** - * Check if the theme supports the section and check user capabilities. + * Checks required user capabilities and whether the theme has the + * feature support required by the section. * * @since 3.4.0 * @@ -71,7 +111,7 @@ class WP_Customize_Section { * * @since 3.4.0 * - * @param WP_Customize_Section $this The WP_Customize_Section instance. + * @param WP_Customize_Section $this WP_Customize_Section instance. */ do_action( 'customize_render_section', $this ); /** @@ -88,7 +128,7 @@ class WP_Customize_Section { } /** - * Render the section. + * Render the section, and the controls that have been added to it. * * @since 3.4.0 */ diff --git a/wp-includes/class-wp-customize-setting.php b/wp-includes/class-wp-customize-setting.php index c7de85ea2f..4cd54e5a30 100644 --- a/wp-includes/class-wp-customize-setting.php +++ b/wp-includes/class-wp-customize-setting.php @@ -2,36 +2,78 @@ /** * Customize Setting Class. * + * Handles saving and sanitizing of settings. + * * @package WordPress * @subpackage Customize * @since 3.4.0 */ class WP_Customize_Setting { + /** + * @access public + * @var WP_Customize_Manager + */ public $manager; + + /** + * @access public + * @var string + */ public $id; - public $type = 'theme_mod'; - public $capability = 'edit_theme_options'; + /** + * @access public + * @var string + */ + public $type = 'theme_mod'; + + /** + * Capability required to edit this setting. + * + * @var string + */ + public $capability = 'edit_theme_options'; + + /** + * Feature a theme is required to support to enable this setting. + * + * @access public + * @var string + */ public $theme_supports = ''; public $default = ''; public $transport = 'refresh'; + /** + * Server-side sanitization callback for the setting's value. + * + * @var callback + */ public $sanitize_callback = ''; public $sanitize_js_callback = ''; protected $id_data = array(); - private $_post_value; // Cached, sanitized $_POST value. + + /** + * Cached and sanitized $_POST value for the setting. + * + * @access private + * @var mixed + */ + private $_post_value; /** * Constructor. * + * Any supplied $args override class property defaults. + * * @since 3.4.0 * * @param WP_Customize_Manager $manager - * @param string $id An specific ID of the setting. Can be a - * theme mod or option name. - * @param array $args Setting arguments. - * @return WP_Customize_Setting + * @param string $id An specific ID of the setting. Can be a + * theme mod or option name. + * @param array $args Setting arguments. + * @return WP_Customize_Setting $setting */ function __construct( $manager, $id, $args = array() ) { $keys = array_keys( get_class_vars( __CLASS__ ) ); @@ -98,7 +140,8 @@ class WP_Customize_Setting { } /** - * Set the value of the parameter for a specific theme. + * Check user capabilities and theme supports, and then save + * the value of the setting. * * @since 3.4.0 * @@ -116,7 +159,7 @@ class WP_Customize_Setting { } /** - * Fetches, validates, and sanitizes the $_POST value. + * Fetch and sanitize the $_POST value for the setting. * * @since 3.4.0 * @@ -124,9 +167,11 @@ class WP_Customize_Setting { * @return mixed The default value on failure, otherwise the sanitized value. */ public final function post_value( $default = null ) { + // Check for a cached value if ( isset( $this->_post_value ) ) return $this->_post_value; + // Call the manager for the post value $result = $this->manager->post_value( $this ); if ( isset( $result ) ) @@ -149,7 +194,7 @@ class WP_Customize_Setting { } /** - * Set the value of the parameter for a specific theme. + * Save the value of the setting, using the related API. * * @since 3.4.0 * @@ -190,7 +235,7 @@ class WP_Customize_Setting { } /** - * Update the theme mod from the value of the parameter. + * Update the option from the value of the setting. * * @since 3.4.0 * @@ -210,13 +255,14 @@ class WP_Customize_Setting { } /** - * Fetch the value of the parameter for a specific theme. + * Fetch the value of the setting. * * @since 3.4.0 * - * @return mixed The requested value. + * @return mixed The value. */ public function value() { + // Get the callback that corresponds to the setting type. switch( $this->type ) { case 'theme_mod' : $function = 'get_theme_mod'; @@ -238,7 +284,7 @@ class WP_Customize_Setting { } /** - * Escape the parameter's value for use in JavaScript. + * Sanitize the setting's value for use in JavaScript. * * @since 3.4.0 * @@ -254,7 +300,7 @@ class WP_Customize_Setting { } /** - * Check if the theme supports the setting and check user capabilities. + * Validate user capabilities whether the theme supports the setting. * * @since 3.4.0 *