X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/61343b82c4f0da4c68e4c6373daafff4a81efdd1..refs/tags/wordpress-4.0:/wp-includes/class-wp-customize-setting.php diff --git a/wp-includes/class-wp-customize-setting.php b/wp-includes/class-wp-customize-setting.php index c8542efe..a516b218 100644 --- a/wp-includes/class-wp-customize-setting.php +++ b/wp-includes/class-wp-customize-setting.php @@ -2,39 +2,81 @@ /** * 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__ ) ); + public function __construct( $manager, $id, $args = array() ) { + $keys = array_keys( get_object_vars( $this ) ); foreach ( $keys as $key ) { if ( isset( $args[ $key ] ) ) $this->$key = $args[ $key ]; @@ -80,7 +122,18 @@ class WP_Customize_Setting { } break; default : - do_action( 'customize_preview_' . $this->id ); + + /** + * Fires when the WP_Customize_Setting::preview() method is called for settings + * not handled as theme_mods or options. + * + * The dynamic portion of the hook name, $this->id, refers to the setting ID. + * + * @since 3.4.0 + * + * @param WP_Customize_Setting $this WP_Customize_Setting instance. + */ + do_action( 'customize_preview_' . $this->id, $this ); } } @@ -98,7 +151,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 * @@ -110,13 +164,23 @@ class WP_Customize_Setting { if ( ! $this->check_capabilities() || ! isset( $value ) ) return false; - do_action( 'customize_save_' . $this->id_data[ 'base' ] ); + /** + * Fires when the WP_Customize_Setting::save() method is called. + * + * The dynamic portion of the hook name, $this->id_data['base'] refers to + * the base slug of the setting name. + * + * @since 3.4.0 + * + * @param WP_Customize_Setting $this WP_Customize_Setting instance. + */ + do_action( 'customize_save_' . $this->id_data[ 'base' ], $this ); $this->update( $value ); } /** - * Fetches, validates, and sanitizes the $_POST value. + * Fetch and sanitize the $_POST value for the setting. * * @since 3.4.0 * @@ -124,9 +188,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 ) ) @@ -145,11 +211,20 @@ class WP_Customize_Setting { */ public function sanitize( $value ) { $value = wp_unslash( $value ); + + /** + * Filter a Customize setting value in un-slashed form. + * + * @since 3.4.0 + * + * @param mixed $value Value of the setting. + * @param WP_Customize_Setting $this WP_Customize_Setting instance. + */ return apply_filters( "customize_sanitize_{$this->id}", $value, $this ); } /** - * Set the value of the parameter for a specific theme. + * Save the value of the setting, using the related API. * * @since 3.4.0 * @@ -160,12 +235,24 @@ class WP_Customize_Setting { switch( $this->type ) { case 'theme_mod' : return $this->_update_theme_mod( $value ); - break; + case 'option' : return $this->_update_option( $value ); - break; + default : - return do_action( 'customize_update_' . $this->type, $value ); + + /** + * Fires when the WP_Customize_Setting::update() method is called for settings + * not handled as theme_mods or options. + * + * The dynamic portion of the hook name, $this->type, refers to the type of setting. + * + * @since 3.4.0 + * + * @param mixed $value Value of the setting. + * @param WP_Customize_Setting $this WP_Customize_Setting instance. + */ + return do_action( 'customize_update_' . $this->type, $value, $this ); } } @@ -190,7 +277,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 +297,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'; @@ -225,6 +313,20 @@ class WP_Customize_Setting { $function = 'get_option'; break; default : + + /** + * Filter a Customize setting value not handled as a theme_mod or option. + * + * The dynamic portion of the hook name, $this->id_date['base'], refers to + * the base slug of the setting name. + * + * For settings handled as theme_mods or options, see those corresponding + * functions for available hooks. + * + * @since 3.4.0 + * + * @param mixed $default The setting default value. Default empty. + */ return apply_filters( 'customize_value_' . $this->id_data[ 'base' ], $this->default ); } @@ -238,13 +340,24 @@ 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 * * @return mixed The requested escaped value. */ public function js_value() { + + /** + * Filter a Customize setting value for use in JavaScript. + * + * The dynamic portion of the hook name, $this->id, refers to the setting ID. + * + * @since 3.4.0 + * + * @param mixed $value The setting value. + * @param WP_Customize_Setting $this WP_Customize_Setting instance. + */ $value = apply_filters( "customize_sanitize_js_{$this->id}", $this->value(), $this ); if ( is_string( $value ) ) @@ -254,7 +367,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 * @@ -420,6 +533,8 @@ final class WP_Customize_Header_Image_Setting extends WP_Customize_Setting { } /** + * Class WP_Customize_Background_Image_Setting + * * @package WordPress * @subpackage Customize * @since 3.4.0