Theme Customizer: Numerous API refinements and bugfixes. Add a theme_supports check for header_textcolor. see #19910.

* prepare_controls() now removes any settings and sections that return false for check_capabilities().
* Added maybe_render() methods to both settings and sections that call the protected render() methods.
* Stop firing front-end preview functionality when rendering the controls.
* Merged the WP_Customize_Setting->_render_type() method into WP_Customize_Setting->render().
* Removed the 'customize_render_control-' hook; use 'customize_render_setting' instead.
* Added a  property to sections and settings so they no longer rely on the  global. Hooray for dependency injection.
* Shifted calls to WP_Customize_Setting->enqueue() to the 'customize_controls_enqueue_scripts' action.
* Added a theme_supports check for the header_textcolor setting.

git-svn-id: https://develop.svn.wordpress.org/trunk@20248 602fd350-edb4-49c9-b593-d223f7449a82

wp-includes/class-wp-customize-section.php

@@ -8,6 +8,7 @@
  */
 
 class WP_Customize_Section {
+	public $manager;
 	public $id;
 	public $priority       = 10;
 	public $capability     = 'edit_theme_options';
@@ -24,15 +25,16 @@ class WP_Customize_Section {
 	 * @param string $id An specific ID of the section.
 	 * @param array $args Section arguments.
 	 */
-	function __construct( $id, $args = array() ) {
+	function __construct( $manager, $id, $args = array() ) {
-		$this->id = $id;
-
 		$keys = array_keys( get_class_vars( __CLASS__ ) );
 		foreach ( $keys as $key ) {
 			if ( isset( $args[ $key ] ) )
 				$this->$key = $args[ $key ];
 		}
 
+		$this->manager = $manager;
+		$this->id = $id;
+
 		$this->settings = array(); // Users cannot customize the $settings array.
 
 		return $this;
@@ -45,7 +47,7 @@ class WP_Customize_Section {
 	 *
 	 * @return bool False if theme doesn't support the section or user doesn't have the capability.
 	 */
-	function check_capabilities() {
+	public final function check_capabilities() {
 		if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) )
 			return false;
 
@@ -55,21 +57,35 @@ class WP_Customize_Section {
 		return true;
 	}
 
+	/**
+	 * Check capabiliites and render the section.
+	 *
+	 * @since 3.4.0
+	 */
+	public final function maybe_render() {
+		if ( ! $this->check_capabilities() )
+			return;
+
+		do_action( 'customize_render_section', $this );
+		do_action( 'customize_render_section_' . $this->id );
+
+		$this->render();
+	}
+
+
 	/**
 	 * Render the section.
 	 *
 	 * @since 3.4.0
 	 */
-	function render() {
+	protected function render() {
-		if ( ! $this->check_capabilities() )
-			return;
 		?>
 		<li id="customize-section-<?php echo esc_attr( $this->id ); ?>" class="control-section customize-section">
 			<h3 class="customize-section-title" title="<?php echo esc_attr( $this->description ); ?>"><?php echo esc_html( $this->title ); ?></h3>
 			<ul class="customize-section-content">
 				<?php foreach ( $this->settings as $setting ) : ?>
 				<li id="customize-control-<?php echo esc_attr( $setting->id ); ?>" class="customize-control customize-control-<?php echo esc_attr( $setting->control ); ?>">
-					<?php $setting->_render(); ?>
+					<?php $setting->maybe_render(); ?>
 				</li>
 				<?php endforeach; ?>
 			</ul>

wp-includes/class-wp-customize-setting.php

@@ -8,6 +8,7 @@
  */
 
 class WP_Customize_Setting {
+	public $manager;
 	public $id;
 	public $priority          = 10;
 	public $section           = '';
@@ -35,13 +36,14 @@ class WP_Customize_Setting {
 	 *                   theme mod or option name.
 	 * @param array $args Setting arguments.
 	 */
-	function __construct( $id, $args = array() ) {
+	function __construct( $manager, $id, $args = array() ) {
 		$keys = array_keys( get_class_vars( __CLASS__ ) );
 		foreach ( $keys as $key ) {
 			if ( isset( $args[ $key ] ) )
 				$this->$key = $args[ $key ];
 		}
 
+		$this->manager = $manager;
 		$this->id = $id;
 
 		// Parse the ID for array keys.
@@ -265,15 +267,13 @@ class WP_Customize_Setting {
 	 * @return bool False if theme doesn't support the setting or user can't change setting, otherwise true.
 	 */
 	public final function check_capabilities() {
-		global $customize;
-
 		if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) )
 			return false;
 
 		if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) )
 			return false;
 
-		$section = $customize->get_section( $this->section );
+		$section = $this->manager->get_section( $this->section );
 		if ( isset( $section ) && ! $section->check_capabilities() )
 			return false;
 
@@ -281,15 +281,16 @@ class WP_Customize_Setting {
 	}
 
 	/**
-	 * Render the control.
+	 * Check capabiliites and render the control.
 	 *
 	 * @since 3.4.0
 	 */
-	public final function _render() {
+	public final function maybe_render() {
 		if ( ! $this->check_capabilities() )
 			return;
 
-		do_action( 'customize_render_' . $this->id );
+		do_action( 'customize_render_setting', $this );
+		do_action( 'customize_render_setting_' . $this->id, $this );
 
 		$this->render();
 	}
@@ -300,39 +301,6 @@ class WP_Customize_Setting {
 	 * @since 3.4.0
 	 */
 	protected function render() {
-		$this->_render_type();
-	}
-
-	/**
-	 * Retrieve the name attribute for an input.
-	 *
-	 * @since 3.4.0
-	 *
-	 * @return string The name.
-	 */
-	public final function get_name() {
-		return self::name_prefix . esc_attr( $this->id );
-	}
-
-	/**
-	 * Echo the HTML name attribute for an input.
-	 *
-	 * @since 3.4.0
-	 *
-	 * @return string The HTML name attribute.
-	 */
-	public final function name() {
-		echo 'name="' . $this->get_name() . '"';
-	}
-
-	/**
-	 * Render the control type.
-	 *
-	 * @todo Improve value and checked attributes.
-	 *
-	 * @since 3.4.0
-	 */
-	public final function _render_type() {
 		switch( $this->control ) {
 			case 'text':
 				?>
@@ -414,12 +382,31 @@ class WP_Customize_Setting {
 				</label>
 				<?php
 				break;
-			default:
-				do_action( 'customize_render_control-' . $this->control, $this );
-
 		}
 	}
 
+	/**
+	 * Retrieve the name attribute for an input.
+	 *
+	 * @since 3.4.0
+	 *
+	 * @return string The name.
+	 */
+	public final function get_name() {
+		return self::name_prefix . esc_attr( $this->id );
+	}
+
+	/**
+	 * Echo the HTML name attribute for an input.
+	 *
+	 * @since 3.4.0
+	 *
+	 * @return string The HTML name attribute.
+	 */
+	public final function name() {
+		echo 'name="' . $this->get_name() . '"';
+	}
+
 	/**
 	 * Multidimensional helper function.
 	 *

wp-includes/class-wp-customize.php

@@ -29,9 +29,10 @@ final class WP_Customize {
 		add_action( 'wp_loaded',    array( $this, 'wp_loaded' ) );
 		add_action( 'admin_footer', array( $this, 'admin_footer' ) );
 
-		add_action( 'customize_previewing',    array( $this, 'customize_previewing' ) );
+		add_action( 'customize_previewing',               array( $this, 'customize_previewing' ) );
-		add_action( 'customize_register',      array( $this, 'register_controls' ) );
+		add_action( 'customize_register',                 array( $this, 'register_controls' ) );
-		add_action( 'customize_controls_init', array( $this, 'prepare_controls' ) );
+		add_action( 'customize_controls_init',            array( $this, 'prepare_controls' ) );
+		add_action( 'customize_controls_enqueue_scripts', array( $this, 'enqueue_control_scripts' ) );
 	}
 
 	/**
@@ -102,8 +103,17 @@ final class WP_Customize {
 	public function wp_loaded() {
 		do_action( 'customize_register' );
 
-		if ( ! $this->is_preview() )
+		if ( $this->is_preview() )
-			return;
+			add_action( 'template_redirect', array( $this, 'customize_preview_init' ) );
+	}
+
+	/**
+	 * Print javascript settings.
+	 *
+	 * @since 3.4.0
+	 */
+	public function customize_preview_init() {
+		$this->prepare_controls();
 
 		wp_enqueue_script( 'customize-preview' );
 		add_action( 'wp_footer', array( $this, 'customize_preview_settings' ), 20 );
@@ -111,8 +121,11 @@ final class WP_Customize {
 		foreach ( $this->settings as $setting ) {
 			$setting->preview();
 		}
+
+		do_action( 'customize_preview_init' );
 	}
 
+
 	/**
 	 * Print javascript settings.
 	 *
@@ -349,7 +362,7 @@ final class WP_Customize {
 	 * @param array $args Setting arguments.
 	 */
 	public function add_setting( $id, $args = array() ) {
-		$setting = new WP_Customize_Setting( $id, $args );
+		$setting = new WP_Customize_Setting( $this, $id, $args );
 
 		$this->settings[ $setting->id ] = $setting;
 	}
@@ -387,7 +400,7 @@ final class WP_Customize {
 	 * @param array $args Section arguments.
 	 */
 	public function add_section( $id, $args = array() ) {
-		$section = new WP_Customize_Section( $id, $args );
+		$section = new WP_Customize_Section( $this, $id, $args );
 
 		$this->sections[ $section->id ] = $section;
 	}
@@ -424,7 +437,7 @@ final class WP_Customize {
 	 * @param object $a Object A.
 	 * @param object $b Object B.
 	 */
-	protected function _cmp_priority( $a, $b ) {
+	protected final function _cmp_priority( $a, $b ) {
 		$ap = $a->priority;
 		$bp = $b->priority;
 
@@ -434,29 +447,49 @@ final class WP_Customize {
 	}
 
 	/**
-	 * Prepare settings and sections. Also enqueue needed scripts/styles.
+	 * Prepare settings and sections.
 	 *
 	 * @since 3.4.0
 	 */
 	public function prepare_controls() {
+		// Prepare settings
 		// Reversing makes uasort sort by time added when conflicts occur.
 
-		$this->sections = array_reverse( $this->sections );
-		uasort( $this->sections, array( $this, '_cmp_priority' ) );
-
 		$this->settings = array_reverse( $this->settings );
-		foreach ( $this->settings as $setting ) {
+		$settings = array();
-			if ( ! isset( $this->sections[ $setting->section ] ) )
+
+		foreach ( $this->settings as $id => $setting ) {
+			if ( ! isset( $this->sections[ $setting->section ] ) || ! $setting->check_capabilities() )
 				continue;
 
 			$this->sections[ $setting->section ]->settings[] = $setting;
-
+			$settings[ $id ] = $setting;
-			if ( $setting->check_capabilities() )
-				$setting->enqueue();
 		}
+		$this->settings = $settings;
+
+		// Prepare sections
+		$this->sections = array_reverse( $this->sections );
+		uasort( $this->sections, array( $this, '_cmp_priority' ) );
+		$sections = array();
 
 		foreach ( $this->sections as $section ) {
+			if ( ! $section->check_capabilities() )
+				continue;
+
 			usort( $section->settings, array( $this, '_cmp_priority' ) );
+			$sections[] = $section;
+		}
+		$this->sections = $sections;
+	}
+
+	/**
+	 * Enqueue scripts for customize controls.
+	 *
+	 * @since 3.4.0
+	 */
+	public function enqueue_control_scripts() {
+		foreach ( $this->settings as $setting ) {
+			$setting->enqueue();
 		}
 	}
 
@@ -479,6 +512,7 @@ final class WP_Customize {
 			'section'           => 'header',
 			'sanitize_callback' => 'sanitize_hexcolor',
 			'control'           => 'color',
+			'theme_supports'    => array( 'custom-header', 'header-text' ),
 			'default'           => get_theme_support( 'custom-header', 'default-text-color' ),
 		) );
 

wp-includes/customize-controls.php

@@ -74,7 +74,7 @@ do_action( 'customize_controls_print_scripts' );
 		<div id="customize-theme-controls"><ul>
 			<?php
 			foreach ( $this->sections as $section )
-				$section->render();
+				$section->maybe_render();
 			?>
 		</ul></div>