IntenseWebs/WordPress
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update the Customizer API inline docs.

Browse Source 
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
2014-03-04 20:21:14 +00:00
parent 0422c70fdb
commit f31ac162f5
5 changed files with 190 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
wp-includes/class-wp-customize-manager.php
View File

@@ -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
*