Presenting capabilities that develop since WordPress 3.4 of the theme customization screen. In addition to the standard features, there will be also presented more unique functions available, including the use of the changes introduced in the newest WordPress versions. The main aim of the lecture is to convince theme developers that the theme customization screen may completely replace additional subpages of the dashboard with theme options.

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

2. Ahoj!

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

6. Why's it worth using the
Theme Customizer?

7. Live preview for setting changes

8. Easy theme-option implementation

9. Test configuration options easily without
affecting the live website

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

11. 4 practical bits of
advice from me to you

12. As the number of options grows, the potential number of
users requesting assistance will grow exponentially too
1
0
Number of options

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

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

15. Solutions implemented in the official APIs
generally work better

16. How does it work?

18. <iframe>

19. <iframe>
refresh
or
JavaScript data binding

20. is_preview()
<iframe>
refresh
or
JavaScript data binding

21. is_preview()
wp_head
<iframe>
refresh
or
JavaScript data binding

22. is_preview()
customize_register
wp_head
<iframe>
refresh
or
JavaScript data binding

23. is_preview()
customize_register
wp_head
<iframe>
customize_preview_init
refresh
or
JavaScript data binding

24. is_preview()
customize_register
wp_head
<iframe>
customize_preview_init
customize_controls_enqueue_scripts
refresh
or
JavaScript data binding

25. Customize Manager

26. Customize Manager
Panel

27. Customize Manager
Panel
Section

28. Customize Manager
Panel
Section
Control

29. Customize Manager
Panel
Section
Control
Setting

30. Customize Manager
Panel
Section
Control
Setting
Context
Context
Context

31. Syntax

32. function PREFIX_customize_register($wp_customizer){
// Theme Customizer code
}

33. function PREFIX_customize_register($wp_customizer){
// Theme Customizer code
}
add_action(
'customize_register',
‘PREFIX_customize_register’
);

34. function PREFIX_customize_register($wp_customizer){
// Theme Customizer code
}
add_action(
'customize_register',
‘PREFIX_customize_register’
);

35. $wp_customizer->add_X(
);

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

37. $wp_customizer->add_X(
‘name’,
);
X = setting, panel, section, control

38. $wp_customizer->add_X(
‘name’,
array(
‘setting_1’ => ‘value’,
‘setting_2’ => ‘value’,
…
‘setting_N’ => ‘value’
)
);
X = setting, panel, section, control

39. $wp_customizer->get_X(‘name’)

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

41. 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 ✔

42. Types of controls

43. text
radio
checkbox
textarea
select
dropdown-pages

44. WP_Customize_Color_ControlWP_Customize_Image_Control

45. More controls

46. $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‘
)
)
);

47. $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‘
)
)
);

48. $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‘
)
)
);

53. But there is a small
problem…

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

55. Custom controls

56. class My_Customize_Textarea_Control extends WP_Customize_Control {
}

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

58. class My_Customize_Textarea_Control extends WP_Customize_Control {
public $type = 'textarea';
public function render_content() {
?>
<?php
}
}

59. 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
}
}

60. 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
}
}

61. 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
}
}

62. 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
}
}

63. $wp_customize->add_control(
);

64. $wp_customize->add_control(
new My_Customize_Textarea_Control(
)
);

65. $wp_customize->add_control(
new My_Customize_Textarea_Control(
$wp_customize,
‘theme_copyright_text’,
)
);

66. $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
)
)
);

67. How to use context?

68. • Hiding unnecessary options

69. • Hiding unnecessary options
• Options dedicated to specific
subpages

70. • Hiding unnecessary options
• Options dedicated to specific
subpages
• Creating dependencies between
options

73. $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'
)
);

74. function mytheme_show_font_field($control) {
}

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

76. function mytheme_show_font_field($control) {
$option = $control->manager->get_setting(‘mytheme_font');
return $option->value() == 'google';
}

77. Problems with
active_callback
is_front_page will work fine as:
“active_callback” => “is_front_page”

78. 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

79. Problems with
active_callback
function PREFIX_is_single() {
return is_single();
}

80. Live preview

82. $wp_customize->add_setting(
'mytheme_primary_color',
array(
'default' => '#5cc1a9',
'capability' => 'edit_theme_options',
'transport' => 'postMessage',
'sanitize_callback' => 'sanitize_hex_color'
)
);

83. $wp_customize->add_setting(
'mytheme_primary_color',
array(
'default' => '#5cc1a9',
'capability' => 'edit_theme_options',
'transport' => 'postMessage',
'sanitize_callback' => 'sanitize_hex_color'
)
);

84. function mytheme_customize_preview_js() {
wp_enqueue_script(
'mytheme-customize-preview',
get_template_directory_uri() . '/js/customize-preview.js',
array(),
‘1.0',
true
);
}

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

86. (function($){
})(jQuery);

87. (function($){
wp.customize(
'mytheme_primary_color',
function(value) {
}
);
})(jQuery);

88. (function($){
wp.customize(
'mytheme_primary_color',
function(value) {
value.bind(function(to) {
});
}
);
})(jQuery);

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

90. Optimisation

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

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

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

94. 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();
}
}
);
});

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

96. Results
BEFORE
• potentially thousands
of DOM operations
• manipulations with
style attributes
AFTER
• maximum 2 DOM
operations
• no manipulations
with style attributes

97. JavaScript API

98. Possibilities
• Access to all elements

99. Possibilities
• Access to all elements
• Re-render of existing elements

100. Possibilities
• Access to all elements
• Re-render of existing elements
• Modification of existing elements

101. Possibilities
• Access to all elements
• Re-render of existing elements
• Modification of existing elements
• Event tracking and control over the preview area

102. function PREFIX_theme_customizer_tooltips() {
?>
<?php
}
add_action(
'customize_controls_print_scripts',
‘PREFIX_theme_customizer_tooltips'
);

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

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

105. Examples

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

107. wp.customize.section("colors").expand();
wp.customize.control("blogname").priority(100);
Examples

108. wp.customize.section("colors").expand();
wp.customize.control("blogname").priority(100);
wp.customize.control("blogname").section("colors");
Examples

109. 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

110. 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

111. Děkuji!

112. Questions?

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