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
This commit is contained in:
Andrew Nacin
parent
0422c70fdb
commit
f31ac162f5
|
|
@ -1,6 +1,6 @@
|
|||
<?php
|
||||
/**
|
||||
* Customize Controls
|
||||
* Theme Customize Screen.
|
||||
*
|
||||
* @package WordPress
|
||||
* @subpackage Customize
|
||||
|
|
@ -9,7 +9,9 @@
|
|||
|
||||
define( 'IFRAME_REQUEST', true );
|
||||
|
||||
/** Load WordPress Administration Bootstrap */
|
||||
require_once( dirname( __FILE__ ) . '/admin.php' );
|
||||
|
||||
if ( ! current_user_can( 'edit_theme_options' ) )
|
||||
wp_die( __( 'Cheatin’ uh?' ) );
|
||||
|
||||
|
|
@ -199,6 +201,7 @@ do_action( 'customize_controls_print_scripts' );
|
|||
'customize-login' => 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;
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
*
|
||||
|
|
|
|||
|
|
@ -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,7 +596,7 @@ final class WP_Customize_Manager {
|
|||
*
|
||||
* @since 3.4.0
|
||||
*
|
||||
* @param string $id A specific ID of the section.
|
||||
* @param WP_Customize_Section|string $id Customize Section object, or Section ID.
|
||||
* @param array $args Section arguments.
|
||||
*/
|
||||
public function add_section( $id, $args = array() ) {
|
||||
|
|
@ -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
|
||||
*
|
||||
|
|
|
|||
|
|
@ -2,23 +2,62 @@
|
|||
/**
|
||||
* 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
|
||||
|
|
@ -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
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
/**
|
||||
* @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
|
||||
* @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
|
||||
*
|
||||
|
|
|
|||
Loading…
Reference in New Issue