WordPress theme customization API

Links:

• Theme_Customization_API
• customize_register
• how-to-leverage-the-theme-customizer-in-your-own-themes
• theme-customizer-part-deux-getting-rid-of-options-pages
• making-a-custom-control-for-the-theme-customizer

customize hook usage:

<?php
add_action( 'customize_register', 'my_customize_register' );
function my_customize_register( $wp_customize ) {
	// customize code
}
?>

4 methods of the $wp_customize object:

<?php
WP_Customize_Manager->add_setting(); // adds a new setting to the database
WP_Customize_Manager->add_section(); // adds a new section (i.e. category/group) to the Theme Customizer page
WP_Customize_Manager->add_control(); // creates an HTML control that admins can use to change settings.
WP_Customize_Manager->get_setting(); // can be used to fetch any existing setting, in the event you need to modify something
?>

customize example:

<?php
add_action( 'customize_register', 'my_customize_register' );
function my_customize_register( $wp_customize ) {
	$wp_customize->get_setting( 'blogname' )->transport = 'postMessage';
	$wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';
	
	
	$wp_customize->add_setting( 'themename_theme_options[theme_footer]', array(
		'default' => 'foter-text default text',
		'type' => 'option',
		'transport' => 'refresh', // refresh (default), postMessage
		//'capability' => 'edit_theme_options',
		//'sanitize_callback' => 'sanitize_key'
	) );
	
	$wp_customize->add_section( 'theme_footer', array(
		'title' => __( 'Footer code', 'themename' ),
		'priority' => 50,
		'description' => __( 'Description of section', 'themename' ),
	) );
	
	$wp_customize->add_control( 'themename_theme_options[theme_footer]', array(
		'section'	=> 'my_footer',
		'type'	 => 'text', // text (default), checkbox, radio, select, dropdown-pages
	) );
	
	// radio control
	$wp_customize->add_control( 'themename_color_scheme', array(
		'label' => __( 'Color Scheme', 'themename' ),
		'section' => 'themename_color_scheme',
		'settings' => 'themename_theme_options[color_scheme]',
		'type' => 'radio',
		'choices' => array(
			'value1' => 'lite',
			'value2' => 'dark',
		),
	) );
	
	// checkbox control
	$wp_customize->add_control( 'display_header_text', array(
		'settings' => 'header_textcolor',
		'label' => __( 'Display Header Text', 'themename' ),
		'section' => 'header',
		'type' => 'checkbox',
	) );
	
	// select control
	$wp_customize->add_control( 'example_select_box', array(
		'label' => 'Select Something:',
		'section' => 'nav',
		'type' => 'select',
		'choices' => array(
			'value1' => 'Choice 1',
			'value2' => 'Choice 2',
			'value3' => 'Choice 3',
		),
	) );
	
	// color control
	$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'theme_footer', array(
		'label'	=> __( 'Link Color', 'themename' ),
		'section' => 'themename_color_scheme',
		'settings' => 'themename_theme_options[link_color]',
	) ) );
	
	// upload control
	$wp_customize->add_control( new WP_Customize_Upload_Control( $wp_customize, 'theme_footer', array(
		'label' => __( 'theme footer', 'themename' ),
		'section' => 'my_footer',
		'settings' => 'themename_theme_options[theme_footer]',
	) ) );
	
	// image control
	$wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize, 'theme_footer', array(
		'label' => __( 'theme footer', 'themename' ),
		'section' => 'my_footer',
		'settings' => 'themename_theme_options[theme_footer]',
	) ) );
	
	// background image control
	$wp_customize->add_control( new WP_Customize_Background_Image_Control( $wp_customize, 'theme_footer', array(
		'label' => __( 'theme footer', 'themename' ),
		'section' => 'my_footer',
		'settings' => 'themename_theme_options[theme_footer]',
	) ) );
	
	// header image control
	$wp_customize->add_control( new WP_Customize_Header_Image_Control( $wp_customize, 'theme_footer', array(
		'label' => __( 'theme footer', 'themename' ),
		'section' => 'my_footer',
		'settings' => 'themename_theme_options[theme_footer]',
	) ) );
	
	
	// textarea control
	$wp_customize->add_control( new WP_Customize_Textarea_Control( $wp_customize, 'theme_footer', array(
		'label'	=> __( 'Textarea', 'themename' ),
		'section' => 'my_footer',
		'settings' => 'themename_theme_options[text]',
	) ) );
	
}


if( class_exists( 'WP_Customize_Control' ) ):
	class WP_Customize_Textarea_Control extends WP_Customize_Control {
		public $type = 'textarea';

		public function render_content() {
			?>
		<label>
			<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
			<textarea rows="5" style="width:100%;" <?php $this->link(); ?>><?php echo esc_textarea( $this->value() ); ?></textarea>
		</label>
		<?php
		}
	}
endif;


add_action( 'admin_menu', 'themename_add_customize_to_admin_menu' );
function themename_add_customize_to_admin_menu() { // add the 'Customize' link to the admin menu
	add_theme_page( 'Customize', 'Customize', 'edit_theme_options', 'customize.php' );
}
?>