The Customizer

The CustomizerKonstantin Obenland

The Customizer Konstantin Obenland

Saturday, September 21, 13

Konstantin ObenlandTheme Wrangler at Automattic

@obenland



What’s The Customizer?





Customizer Anatomy



Customizer Anatomy

Section Title



Customizer Anatomy

Section Description



Customizer Anatomy

Control



Relationships within the Customizer

Control

Control

Control

Control

Section

Setting

Setting

Setting

Setting

Database Section

Section



Theme Mods & OptionsDigression



Options

“The Options API is a simple and standardized way of storing data in the database.” — WordPress Codex



Theme Modifications

• Options API for themes.

• Introduced in 2.1 (!)



Theme Mods API

set_theme_mod( $name, $value );get_theme_mod( $name, $default = false );remove_theme_mod( $name );

get_theme_mods();remove_theme_mods();



Theme Mods API

// Function simplified for brevity and clarity.function get_theme_mod( $name, $default = false ) { $mods = get_option( 'theme_mods_' . get_option( 'stylesheet' ) );

if ( isset( $mods[ $name ] ) ) return $mods[ $name ];

return $default;}



The Customizer API



Get Started

/** * Registers the theme setting controls with the Customizer. * * @param WP_Customize_Manager $wp_customize */function prefix_customize_register( $wp_customize ) {

// Code

}add_action( 'customize_register', 'prefix_customize_register' );



Adding a Section

$wp_customize->add_section( 'unique_section_id', array( 'title' => __( 'Title', 'textdomain' ), 'priority' => 10, 'description' => __( 'Description', 'textdomain' ), 'theme_supports' => '', 'capability' => 'edit_theme_options',) );



Adding a Setting

$wp_customize->add_setting( 'settings_name', array( 'type' => 'theme_mod', // 'option' 'capability' => 'edit_theme_options', 'theme_supports' => '', 'default' => '', 'transport' => 'refresh', // 'postMessage' 'sanitize_callback' => '', 'sanitize_js_callback' => '',) );



Adding a Control

$wp_customize->add_control( 'unique_control_id', array( 'label' => __( 'Label', 'textdomain' ), 'section' => 'unique_section_id', 'priority' => 10, 'settings' => 'unique_settings_id', 'type' => 'radio', // 'text','checkbox','select','dropdown-pages' 'choices' => array( 'value' => __( 'Choice', 'textdomain' ), ),) );



Customizer Anatomy



$this->add_section( 'title_tagline', array( 'title' => __( 'Site Title & Tagline' ), 'priority' => 20,) );

$this->add_setting( 'blogname', array( 'default' => get_option( 'blogname' ), 'type' => 'option', 'capability' => 'manage_options',) );

$this->add_control( , array( 'label' => __( 'Site Title' ), 'section' => ,) );

A Complete Setting'title_tagline'

'blogname'






A Complete Setting

'title_tagline'

'blogname'






A Complete Setting

'title_tagline'

'blogname'



Validation & Sanitization



function prefix_customize_register( $wp_customize ) { $wp_customize->add_setting( 'prefix_layout', array( 'default' => 'content-sidebar', 'sanitize_callback' => 'prefix_sanitize_layout', // 'is_email', 'esc_url_raw' ) );

$wp_customize->add_control( 'prefix_layout', $args );}add_action( 'customize_register', 'prefix_customize_register' );

function prefix_sanitize_layout( $value ) { if ( ! in_array( $value, array( 'content-sidebar', 'sidebar-content' ) ) ) $value = 'content-sidebar';

return $value;}

Validation & Sanitization The Customizer Konstantin Obenland


function prefix_customize_register( $wp_customize ) { $wp_customize->add_setting( 'prefix_theme_options[layout]', array( 'default' => 'content-sidebar', 'type' => 'option', ) );

$wp_customize->add_control( 'prefix_theme_options[layout]', $args );}add_action( 'customize_register', 'prefix_customize_register' );

function prefix_sanitize_customizer( $option ) { if ( ! isset( $option['prefix_layout'] ) || ! in_array( $option['prefix_layout'], array( 'content-sidebar', 'sidebar-content' ) ) ) $option['prefix_layout'] = 'content-sidebar'; return $option;}register_setting( 'prefix_theme_options', 'prefix_theme_options', 'prefix_sanitize_customizer' );

Validation & Sanitization The Customizer Konstantin Obenland


Transport Methods



$wp_customize->add_setting( 'unique_settings_id', array( 'default' => '', 'transport' => 'postMessage', // 'refresh') );

Transport Methods The Customizer Konstantin Obenland



/** * Add postMessage support for site title and description for the Customizer. * * @since Twenty Thirteen 1.0 * * @param WP_Customize_Manager $wp_customize Customizer object. * @return void */function twentythirteen_customize_register( $wp_customize ) { $wp_customize->get_setting( 'blogname' )->transport = 'postMessage'; $wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage'; $wp_customize->get_setting( 'header_textcolor' )->transport = 'postMessage';}add_action( 'customize_register', 'twentythirteen_customize_register' );

In Twenty Thirteen The Customizer Konstantin Obenland


/** * Binds JavaScript handlers to make Customizer preview reload changes * asynchronously. * * @since Twenty Thirteen 1.0 */function twentythirteen_customize_preview_js() { wp_enqueue_script( 'twentythirteen-customizer', get_template_directory_uri() . '/js/theme-customizer.js', array( 'customize-preview' ), '20130226', true );}add_action( 'customize_preview_init', 'twentythirteen_customize_preview_js' );



/** * Theme Customizer enhancements for a better user experience. * Contains handlers to make Theme Customizer preview reload changes asynchronously. */( function( $ ) { // Site title and description. wp.customize( 'blogname', function( value ) { value.bind( function( to ) { $( '.site-title' ).text( to ); } ); } ); wp.customize( 'blogdescription', function( value ) { value.bind( function( to ) { $( '.site-description' ).text( to ); } ); } );} )( jQuery );



wp.customize( 'header_textcolor', function( value ) { value.bind( function( to ) { if ( 'blank' == to ) { if ( 'remove-header' == _wpCustomizeSettings.values.header_image ) $( '.home-link' ).css( 'min-height', '0' ); $( '.site-title, .site-description' ).css( { 'clip': 'rect(1px, 1px, 1px, 1px)', 'position': 'absolute' } ); } else { $( '.home-link' ).css( 'min-height', '230px' ); $( '.site-title, .site-description' ).css( { 'clip': 'auto', 'color': to, 'position': 'relative' } ); } } );} );



Custom Controls



Built-in Controls The Customizer Konstantin Obenland


class Prefix_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" <?php $this->link(); ?>> <?php echo esc_textarea( $this->value() ); ?> </textarea> </label> <?php }}

Custom Controls The Customizer Konstantin Obenland


Built-in Custom Controls

WP_Customize_Color_Control

WP_Customize_Upload_Control

WP_Customize_Image_Control

WP_Customize_Background_Image_Control

WP_Customize_Header_Image_Control



WP_Customize_Image_Control



WP_Customize_Color_Control



$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'accent_color', array( 'label' => __( 'Accent Color', 'twentyfourteen' ), 'section' => 'colors', 'settings' => 'accent_color',) ) );

Custom Controls The Customizer Konstantin Obenland


Thanks!Questions?



Business

The Customizer