WordCamp Praga 2015

Discovering the capabilities of the Theme Customizer API

Tomasz Dziuda

WordCamp Praha 2015

Ahoj!

Tomasz Dziuda

Lead Developer @

Co-organizer of WordCamp Poland 2014

Twitter: @dziudek

http://dziudek.pl -> https://www.gavick.com/blog

Mail: [email protected]

Why's it worth using the Theme Customizer?

Live preview for setting changes

Easy theme-option implementation

Test configuration options easily without affecting the live website

A user doesn’t have to learn how to use the theme settings page

4 practical bits of advice from me to you

As the number of options grows, the potential number of users requesting assistance will grow exponentially too

1

0Number of options

Giving a user full control over colors, in most cases, ends with dramatic results

The Dashboard will accept everything, but the user won't

Solutions implemented in the official APIs generally work better

How does it work?

<iframe>

<iframe>

refreshor

JavaScript data binding

is_preview()

<iframe>

refreshor

JavaScript data binding

is_preview()wp_head

<iframe>

refreshor

JavaScript data binding

is_preview()

customize_register

wp_head

<iframe>

refreshor

JavaScript data binding

is_preview()

customize_register

wp_head

<iframe>

customize_preview_init

refreshor

JavaScript data binding

is_preview()

customize_register

wp_head

<iframe>

customize_preview_init

customize_controls_enqueue_scripts

refreshor

JavaScript data binding

Customize Manager

Customize Manager

Panel

Customize Manager

Panel

Section

Customize Manager

Panel

Section

Control

Customize Manager

Panel

Section

Control

Setting

Customize Manager

Panel

Section

Control

Setting

Context

Context

Context

Syntax

function PREFIX_customize_register($wp_customizer){// Theme Customizer code

}

function PREFIX_customize_register($wp_customizer){// Theme Customizer code

}

add_action('customize_register', ‘PREFIX_customize_register’

);

function PREFIX_customize_register($wp_customizer){// Theme Customizer code

}

add_action('customize_register', ‘PREFIX_customize_register’

);

$wp_customizer->add_X(

);

$wp_customizer->add_X(

);

X = setting, panel, section, control

$wp_customizer->add_X(‘name’,

);

X = setting, panel, section, control

$wp_customizer->add_X(‘name’,array(

‘setting_1’ => ‘value’,‘setting_2’ => ‘value’,…‘setting_N’ => ‘value’

));

X = setting, panel, section, control

$wp_customizer->get_X(‘name’)

$wp_customizer->get_X(‘name’)

$wp_customizer->remove_X(‘name’)

Available paramsparam / element panel section control setting

type ✔ ✔ ✔ ✔

description ✔ ✔ ✔

priority ✔ ✔ ✔

capability ✔ ✔ ✔

theme_supports ✔ ✔ ✔

title ✔ ✔

panel ✔

section ✔

label ✔

choices ✔

input_attrs ✔

active_callback ✔

sanitize_callback ✔

sanitize_js_callback ✔

default ✔

transport ✔

Types of controls

text

radio

checkbox

textarea

select

dropdown-pages

WP_Customize_Color_ControlWP_Customize_Image_Control

More controls

$wp_customize->add_control( ‘mytheme_layout_width’, array(

'type' => 'range', 'section' => 'layout', 'label' => ‘Layout width', 'input_attrs' => array( 'min' => 720, 'max' => 1280, 'step' => 1, 'class' => ‘layout-width-control‘ ) ) );

$wp_customize->add_control( ‘mytheme_layout_width’, array(

'type' => 'range', 'section' => 'layout', 'label' => ‘Layout width', 'input_attrs' => array( 'min' => 720, 'max' => 1280, 'step' => 1, 'class' => ‘layout-width-control‘ ) ) );

$wp_customize->add_control( ‘mytheme_layout_width’, array(

'type' => 'range', 'section' => 'layout', 'label' => ‘Layout width', 'input_attrs' => array( 'min' => 720, 'max' => 1280, 'step' => 1, 'class' => ‘layout-width-control‘ ) ) );

But there is a small problem…

Source: http://caniuse.com/#search=date

Custom controls

class My_Customize_Textarea_Control extends WP_Customize_Control {

}

class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea';

}

class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea'; public function render_content() {?>

<?php}

}

class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea'; public function render_content() {?>

<label><?php if(!empty($this->label)) : ?><span class=“customize-control-title">

<?php echo esc_html( $this->label ); ?></span><?php endif; ?>

</label><?php}

}

class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea'; public function render_content() {?>

<label><?php if(!empty($this->label)) : ?><span class=“customize-control-title">

<?php echo esc_html( $this->label ); ?></span><?php endif; ?><?php if(!empty($this->description)) : ?><span class="description customize-control-description”>

<?php echo $this->description ; ?></span><?php endif; ?>

</label><?php}

}

class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea'; public function render_content() {?>

<label><?php if(!empty($this->label)) : ?><span class=“customize-control-title">

<?php echo esc_html( $this->label ); ?></span><?php endif; ?><?php if(!empty($this->description)) : ?><span class="description customize-control-description”>

<?php echo $this->description ; ?></span><?php endif; ?><textarea rows=“5" cols=“20” <?php $this->link(); ?>><?php echo esc_textarea($this->value()); ?></textarea>

</label><?php}

}

class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea'; public function render_content() {?>

<label><?php if(!empty($this->label)) : ?><span class=“customize-control-title">

<?php echo esc_html( $this->label ); ?></span><?php endif; ?><?php if(!empty($this->description)) : ?><span class="description customize-control-description”>

<?php echo $this->description ; ?></span><?php endif; ?><textarea rows=“5" cols=“20” <?php $this->link(); ?>><?php echo esc_textarea($this->value()); ?></textarea>

</label><?php}

}

$wp_customize->add_control(

);

$wp_customize->add_control( new My_Customize_Textarea_Control(

));

$wp_customize->add_control( new My_Customize_Textarea_Control( $wp_customize, ‘theme_copyright_text’,

));

$wp_customize->add_control( new My_Customize_Textarea_Control( $wp_customize, ‘theme_copyright_text’,

array( 'label' => __(‘Copyright text', 'theme'), 'section' => 'features',

'settings' => ‘theme_copyright_text’, 'priority' => 2

))

);

How to use context?

• Hiding unnecessary options

• Hiding unnecessary options

• Options dedicated to specific subpages

• Hiding unnecessary options

• Options dedicated to specific subpages

• Creating dependencies between options

$wp_customize->add_control('mytheme_google_font',array(

'section' => 'mytheme_font_options','label' => __('Google Font URL', 'mytheme'),'type' => 'text','active_callback' => 'mytheme_show_font_field'

));

function mytheme_show_font_field($control) {

}

function mytheme_show_font_field($control) {$option = $control->manager->get_setting(‘mytheme_font');

}

function mytheme_show_font_field($control) {$option = $control->manager->get_setting(‘mytheme_font');

return $option->value() == 'google';}

Problems with active_callback

is_front_page will work fine as:

“active_callback” => “is_front_page”

Problems with active_callback

is_front_page will work fine as:

“active_callback” => “is_front_page”

but is_single or is_singular won’t, because they take an argument which in this case is a handler to

the panel/section/control

Problems with active_callback

function PREFIX_is_single() {

return is_single();

}

Live preview

$wp_customize->add_setting( 'mytheme_primary_color', array(

'default' => '#5cc1a9', 'capability' => 'edit_theme_options',

'transport' => 'postMessage', 'sanitize_callback' => 'sanitize_hex_color'

));

$wp_customize->add_setting( 'mytheme_primary_color', array(

'default' => '#5cc1a9', 'capability' => 'edit_theme_options',

'transport' => 'postMessage', 'sanitize_callback' => 'sanitize_hex_color'

));

function mytheme_customize_preview_js() {wp_enqueue_script(

'mytheme-customize-preview', get_template_directory_uri() . '/js/customize-preview.js', array(), ‘1.0', true

);}

function mytheme_customize_preview_js() {wp_enqueue_script(

'mytheme-customize-preview', get_template_directory_uri() . '/js/customize-preview.js', array(), ‘1.0', true

);}

add_action('customize_preview_init', ‘mytheme_customize_preview_js'

);

(function($){

})(jQuery);

(function($){ wp.customize(

'mytheme_primary_color', function(value) {

} );})(jQuery);

(function($){ wp.customize(

'mytheme_primary_color', function(value) {

value.bind(function(to) { }); } );})(jQuery);

(function($){ wp.customize(

'mytheme_primary_color', function(value) {

value.bind(function(to) { jQuery('a').css('color', to || '#5cc1a9'); }); } );})(jQuery);

Optimisation

wp.customize('mytheme_primary_color', function(value) { value.bind( function( to ) {

} );});

wp.customize('mytheme_primary_color', function(value) { value.bind( function( to ) { to = to || '#5cc1a9';

} );});

wp.customize('mytheme_primary_color', function(value) { value.bind( function( to ) { to = to || '#5cc1a9'; var new_css = 'a { color: ' + to + '; }';

} );});

wp.customize('mytheme_primary_color', function(value) { value.bind( function( to ) { to = to || '#5cc1a9'; var new_css = 'a { color: ' + to + '; }'; if($('#new-css').length) { $('#new-css').remove(); }

} );});

wp.customize('mytheme_primary_color', function(value) { value.bind( function( to ) { to = to || '#5cc1a9'; var new_css = 'a { color: ' + to + '; }'; if($('#new-css').length) { $('#new-css').remove(); } $(document).find('head') .append($('<style id="new-css">' + new_css + '</style>')); }

);});

Results

BEFORE

• potentially thousands of DOM operations

• manipulations with style attributes

AFTER

• maximum 2 DOM operations

• no manipulations with style attributes

JavaScript API

Possibilities

• Access to all elements

Possibilities

• Access to all elements

• Re-render of existing elements

Possibilities

• Access to all elements

• Re-render of existing elements

• Modification of existing elements

Possibilities

• Access to all elements

• Re-render of existing elements

• Modification of existing elements

• Event tracking and control over the preview area

function PREFIX_theme_customizer_tooltips() { ?>

<?php} add_action('customize_controls_print_scripts', ‘PREFIX_theme_customizer_tooltips');

function PREFIX_theme_customizer_tooltips() { ?> <script type="text/javascript"> jQuery(document).ready(function() {

}); </script> <?php} add_action('customize_controls_print_scripts', ‘PREFIX_theme_customizer_tooltips');

function PREFIX_theme_customizer_tooltips() { ?> <script type="text/javascript"> jQuery(document).ready(function() { wp.customize.bind('ready', function() { // Your Theme Customizer Code }); }); </script> <?php} add_action('customize_controls_print_scripts', ‘PREFIX_theme_customizer_tooltips');

Examples

wp.customize.section("colors").expand();

Examples

wp.customize.section("colors").expand();

wp.customize.control("blogname").priority(100);

Examples

wp.customize.section("colors").expand();

wp.customize.control("blogname").priority(100);

wp.customize.control("blogname").section("colors");

Examples

wp.customize.section("colors").expand();

wp.customize.control("blogname").priority(100);

wp.customize.control("blogname").section("colors");

var ctrl = wp.customize.control("background_color");ctrl.params.label = "New label";ctrl.renderContent();ctrl.ready();

Examples

Reading list• https://www.gavick.com/blog/live-preview-themes-colors-changes-theme-

customizer

• https://www.gavick.com/blog/contextual-controls-theme-customizer

• https://www.gavick.com/blog/theme-customization-controls

• https://www.gavick.com/blog/custom-control-wordpress-theme-customizer

• https://www.gavick.com/blog/custom-category-selection-controls

• https://www.gavick.com/blog/using-javascript-theme-customization-screen

• https://www.gavick.com/blog/using-tooltips-instead-option-descriptions-wordpress-theme-customizer

• https://www.gavick.com/blog/internal-linking-wordpress-theme-customizer

Děkuji!

Questions?

This presentation is available under the GPL license:

http://www.gnu.org/copyleft/gpl.html