The Customizer

The CustomizerKonstantin Obenland

The Customizer Konstantin Obenland

Saturday, September 21, 13

Konstantin ObenlandTheme Wrangler at Automattic

@obenland

The Customizer Konstantin Obenland

Saturday, September 21, 13

What’s The Customizer?

The Customizer Konstantin Obenland

Saturday, September 21, 13

The Customizer Konstantin Obenland

Saturday, September 21, 13

Customizer Anatomy

The Customizer Konstantin Obenland

Saturday, September 21, 13

Customizer Anatomy

Section Title

The Customizer Konstantin Obenland

Saturday, September 21, 13

Customizer Anatomy

Section Description

The Customizer Konstantin Obenland

Saturday, September 21, 13

Customizer Anatomy

Control

The Customizer Konstantin Obenland

Saturday, September 21, 13

Relationships within the Customizer

Control

Control

Control

Control

Section

Setting

Setting

Setting

Setting

Database Section

Section

The Customizer Konstantin Obenland

Saturday, September 21, 13

Theme Mods & OptionsDigression

The Customizer Konstantin Obenland

Saturday, September 21, 13

Options

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

The Customizer Konstantin Obenland

Saturday, September 21, 13

Theme Modifications

• Options API for themes.

• Introduced in 2.1 (!)

The Customizer Konstantin Obenland

Saturday, September 21, 13

Theme Mods API

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

get_theme_mods();remove_theme_mods();

The Customizer Konstantin Obenland

Saturday, September 21, 13

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 Konstantin Obenland

Saturday, September 21, 13

The Customizer API

The Customizer Konstantin Obenland

Saturday, September 21, 13

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' );

The Customizer Konstantin Obenland

Saturday, September 21, 13

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',) );

The Customizer Konstantin Obenland

Saturday, September 21, 13

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' => '',) );

The Customizer Konstantin Obenland

Saturday, September 21, 13

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' ), ),) );

The Customizer Konstantin Obenland

Saturday, September 21, 13

Customizer Anatomy

The Customizer Konstantin Obenland

Saturday, September 21, 13

$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'

The Customizer Konstantin Obenland

Saturday, September 21, 13

$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'

The Customizer Konstantin Obenland

Saturday, September 21, 13

$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'

The Customizer Konstantin Obenland

Saturday, September 21, 13

Validation & Sanitization

The Customizer Konstantin Obenland

Saturday, September 21, 13

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

Saturday, September 21, 13

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

Saturday, September 21, 13

Transport Methods

The Customizer Konstantin Obenland

Saturday, September 21, 13

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

Transport Methods The Customizer Konstantin Obenland

Saturday, September 21, 13

Saturday, September 21, 13

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

Saturday, September 21, 13

/** * 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' );

In Twenty Thirteen The Customizer Konstantin Obenland

Saturday, September 21, 13

/** * 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 );

In Twenty Thirteen The Customizer Konstantin Obenland

Saturday, September 21, 13

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' } ); } } );} );

In Twenty Thirteen The Customizer Konstantin Obenland

Saturday, September 21, 13

Custom Controls

The Customizer Konstantin Obenland

Saturday, September 21, 13

Built-in Controls The Customizer Konstantin Obenland

Saturday, September 21, 13

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

Saturday, September 21, 13

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

The Customizer Konstantin Obenland

Saturday, September 21, 13

WP_Customize_Image_Control

The Customizer Konstantin Obenland

Saturday, September 21, 13

WP_Customize_Color_Control

The Customizer Konstantin Obenland

Saturday, September 21, 13

$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

Saturday, September 21, 13

Thanks!Questions?

The Customizer Konstantin Obenland

Saturday, September 21, 13