_s: Update Custom Header Code. fixes #1212

* Use WordPress 3.4's registration method providing backward compatibility for previous versions.
* Implement shiv for get_custom_header(). props @obenland
* Allow all custom header args to be filtered via child theme/plugin.
* Update example code in DocBlock to use get_custom_header().



git-svn-id: https://wpcom-themes.svn.automattic.com/_s/@9484 d957f892-c61d-0410-b221-f235e6eecf30

inc/custom-header.php

@@ -8,7 +8,7 @@
 	<?php $header_image = get_header_image();
 	if ( ! empty( $header_image ) ) { ?>
 		<a href="<?php echo esc_url( home_url( '/' ) ); ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
-			<img src="<?php header_image(); ?>" width="<?php echo HEADER_IMAGE_WIDTH; ?>" height="<?php echo HEADER_IMAGE_HEIGHT; ?>" alt="" />
+			<img src="<?php header_image(); ?>" width="<?php echo get_custom_header()->width; ?>" height="<?php echo get_custom_header()->height; ?>" alt="" />
 		</a>
 	<?php } // if ( ! empty( $header_image ) ) ?>
 
@@ -17,30 +17,78 @@
  * @since _s 1.0
  */
 
+/**
+ * Setup the WordPress core custom header feature.
+ *
+ * Use add_theme_support to register support for WordPress 3.4+
+ * as well as provide backward compatibility for previous versions.
+ * Use feature detection of wp_get_theme() which was introduced
+ * in WordPress 3.4.
+ *
+ * @uses _s_header_style()
+ * @uses _s_admin_header_style()
+ * @uses _s_admin_header_image()
+ *
+ * @package _s
+ */
 function _s_custom_header_setup() {
-	// The default header text color
+	$args = array(
-	define( 'HEADER_TEXTCOLOR', '000' );
+		'default-image'          => '',
+		'default-text-color'     => '000',
+		'width'                  => 1000,
+		'height'                 => 250,
+		'flex-height'            => true,
+		'wp-head-callback'       => '_s_header_style',
+		'admin-head-callback'    => '_s_admin_header_style',
+		'admin-preview-callback' => '_s_admin_header_image',
+	);
 
-	// By leaving empty, we allow for random image rotation.
+	$args = apply_filters( '_s_custom_header_args', $args );
-	define( 'HEADER_IMAGE', '' );
 
-	// The height and width of your custom header.
+	if ( function_exists( 'wp_get_theme' ) ) {
-	// Add a filter to _s_header_image_width and _s_header_image_height to change these values.
+		add_theme_support( 'custom-header', $args );
-	define( 'HEADER_IMAGE_WIDTH', apply_filters( '_s_header_image_width', 1000 ) );
+	} else {
-	define( 'HEADER_IMAGE_HEIGHT', apply_filters( '_s_header_image_height', 250 ) );
+		// Compat: Versions of WordPress prior to 3.4.
-
+		define( 'HEADER_TEXTCOLOR',    $args['default-text-color'] );
-	// Turn on random header image rotation by default.
+		define( 'HEADER_IMAGE',        $args['default-image'] );
-	add_theme_support( 'custom-header', array( 'random-default' => true ) );
+		define( 'HEADER_IMAGE_WIDTH',  $args['width'] );
-
+		define( 'HEADER_IMAGE_HEIGHT', $args['height'] );
-	// Add a way for the custom header to be styled in the admin panel that controls custom headers
+		add_custom_image_header( $args['wp-head-callback'], $args['admin-head-callback'], $args['admin-preview-callback'] );
-	add_custom_image_header( '_s_header_style', '_s_admin_header_style', '_s_admin_header_image' );
+	}
 }
 add_action( 'after_setup_theme', '_s_custom_header_setup' );
 
+/**
+ * Shiv for get_custom_header().
+ *
+ * get_custom_header() was introduced to WordPress
+ * in version 3.4. To provide backward compatibility
+ * with previous versions, we will define our own version
+ * of this function.
+ *
+ * @return stdClass All properties represent attributes of the curent header image.
+ *
+ * @package _s
+ * @since _s 1.1
+ */
+
+if ( ! function_exists( 'get_custom_header' ) ) {
+	function get_custom_header() {
+		return (object) array(
+			'url'           => get_header_image(),
+			'thumbnail_url' => get_header_image(),
+			'width'         => HEADER_IMAGE_WIDTH,
+			'height'        => HEADER_IMAGE_HEIGHT,
+		);
+	}
+}
+
 if ( ! function_exists( '_s_header_style' ) ) :
 /**
  * Styles the header image and text displayed on the blog
  *
+ * @see _s_custom_header_setup().
+ *
  * @since _s 1.0
  */
 function _s_header_style() {
@@ -80,7 +128,7 @@ if ( ! function_exists( '_s_admin_header_style' ) ) :
 /**
  * Styles the header image displayed on the Appearance > Header admin panel.
  *
- * Referenced via add_custom_image_header() in _s_setup().
+ * @see _s_custom_header_setup().
  *
  * @since _s 1.0
  */
@@ -110,7 +158,7 @@ if ( ! function_exists( '_s_admin_header_image' ) ) :
 /**
  * Custom header image markup displayed on the Appearance > Header admin panel.
  *
- * Referenced via add_custom_image_header() in _s_setup().
+ * @see _s_custom_header_setup().
  *
  * @since _s 1.0
  */