The Customizer

The Customizer
Konstantin Obenland
 The Customizer Konstantin Obenland 
Saturday, September 21, 13

Konstantin Obenland
Theme 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
DatabaseSection
Section

Theme Mods & Options
Digression

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

Theme Modiﬁcations
• 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' ),
),
) );

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

Validation & Sanitization

$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 );
}
function prefix_sanitize_layout( $value ) {
if ( ! in_array( $value, array( 'content-sidebar', 'sidebar-content' ) ) )
$value = 'content-sidebar';
return $value;
}

$wp_customize->add_setting( 'prefix_theme_options[layout]', array(
'default' => 'content-sidebar',
'type' => 'option',
) );
$wp_customize->add_control( 'prefix_theme_options[layout]', $args );
}
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' );

Transport Methods

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

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

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

/**
* 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 ) {
$( '.site-description' ).text( to );
} );
} );
} )( jQuery );
In Twenty Thirteen

wp.customize( 'header_textcolor', function( value ) {
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

Custom Controls

Built-in Controls

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

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

Thanks!
Questions?

The Customizer

Recommandé

Recommandé

Contenu connexe

En vedette

En vedette (15)

Similaire à The Customizer

Similaire à The Customizer (20)

Plus de Konstantin Obenland

Plus de Konstantin Obenland (8)

Dernier

Dernier (20)

The Customizer