WordCamp Praga 2015

Discovering the capabilities of
the Theme Customizer API
Tomasz Dziuda
WordCamp Praha 2015

Tomasz Dziuda
Lead Developer @
Co-organizer of WordCamp Poland 2014
Twitter: @dziudek
http://dziudek.pl -> https://www.gavick.com/blog
Mail: dziudek@gavick.com

Why's it worth using the
Theme Customizer?

Live preview for setting changes

Easy theme-option implementation

Test conﬁguration 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
0
Number 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 ofﬁcial APIs
generally work better

is_preview()
<iframe>
refresh
or

is_preview()
wp_head
<iframe>
refresh
or

is_preview()
customize_register
wp_head
<iframe>
refresh
or

is_preview()
customize_register
wp_head
<iframe>
customize_preview_init
refresh
or

is_preview()
customize_register
wp_head
<iframe>
customize_preview_init
customize_controls_enqueue_scripts
refresh
or

Customize Manager
Panel
Section

Customize Manager
Panel
Section
Control

Customize Manager
Panel
Section
Control
Setting

Customize Manager
Panel
Section
Control
Setting
Context
Context
Context

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

$wp_customizer->add_X(
);
X = setting, panel, section, control

‘name’,
);

‘name’,
array(
‘setting_1’ => ‘value’,
‘setting_2’ => ‘value’,
…
‘setting_N’ => ‘value’
)
);

$wp_customizer->get_X(‘name’)

$wp_customizer->get_X(‘name’)
$wp_customizer->remove_X(‘name’)

Available params
param / 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 ✔

text
radio
checkbox
textarea
select
dropdown-pages

WP_Customize_Color_ControlWP_Customize_Image_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

class My_Customize_Textarea_Control extends WP_Customize_Control {
}

public $type = 'textarea';
}

public function render_content() {
?>
<?php
}
}

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

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

?>
<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
}
}

);

new My_Customize_Textarea_Control(
)
);

$wp_customize,
‘theme_copyright_text’,
)
);

$wp_customize,
‘theme_copyright_text’,
array(
'label' => __(‘Copyright text', 'theme'),
'section' => 'features',
'settings' => ‘theme_copyright_text’,
'priority' => 2
)
)
);

• Hiding unnecessary options

• Options dedicated to speciﬁc
subpages

• Options dedicated to speciﬁc
subpages
• Creating dependencies between
options

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

$option = $control->manager->get_setting(‘mytheme_font');
}

$option = $control->manager->get_setting(‘mytheme_font');
return $option->value() == 'google';
}

Problems with
active_callback
is_front_page will work ﬁne as:
“active_callback” => “is_front_page”

Problems with
active_callback
is_front_page will work ﬁne 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();
}

$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($){
wp.customize(
function(value) {
}
);
})(jQuery);

(function($){
wp.customize(
function(value) {
value.bind(function(to) {
});
}
);
})(jQuery);

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

wp.customize(
function(value) {
value.bind( function( to ) {
}
);
});

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

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

wp.customize(
function(value) {
to = to || '#5cc1a9';
if($('#new-css').length) {
$('#new-css').remove();
}
}
);
});

wp.customize(
function(value) {
to = to || '#5cc1a9';
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

Possibilities
• Access to all elements

Possibilities
• Re-render of existing elements

Possibilities
• Modiﬁcation of existing elements

Possibilities
• Modiﬁcation 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'
);

?>
<script type="text/javascript">
jQuery(document).ready(function() {
});
</script>
<?php
}
add_action(
);

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

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

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

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

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

This presentation is available under the GPL license:
http://www.gnu.org/copyleft/gpl.html

WordCamp Praga 2015

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (6)

Similar to WordCamp Praga 2015

Similar to WordCamp Praga 2015 (20)

More from Tomasz Dziuda

More from Tomasz Dziuda (20)

Recently uploaded

Recently uploaded (20)

WordCamp Praga 2015