1. r3df.com
lumostech.training
Rick Radko
“Creating Customizer Options
for Themes and Plugins”
WordCamp Toronto
October 4th, 2015
Slides at: slideshare.net/r3df

2. © 2015 Rick Radko, r3df.com
What's this talk about?
 An introduction to adding customizer options to
your plugins and themes.
Topics:
 Introduction
 Brief introduction to customizer
 Creating customizer options
 4 steps
 Using the options
 Beyond the Basics
1Slides at: slideshare.net/r3df

3. © 2015 Rick Radko, r3df.com
Objectives of this talk:
 Demonstrate that it is easy to add basic
customizer options to plugins and themes.
 Encourage you to start using the customizer for
your options.
For code examples for this presentation, I'm going
to use a plugin I created recently:
 wordpress.org/plugins/r3df-copyright-message
 (Version 1.1.0)
2Slides at: slideshare.net/r3df

4. © 2015 Rick Radko, r3df.com
About me
 Rick Radko, @r3designforge
Software, website and app designer/developer,
trainer, speaker.
 R-Cubed Design Forge: r3df.com
 LumosTech Training: lumostech.training
Creating custom web sites since 1996.
 WordPress sites since 2008.
An organizer of:
 WordCamp Ottawa.
 The Ottawa WordPress Group.
3Slides at: slideshare.net/r3df

5. © 2015 Rick Radko, r3df.com
Theme Customizer - WordPress 3.4
4

6. © 2015 Rick Radko, r3df.com
Customizer in 4.3
5

7. © 2015 Rick Radko, r3df.com
Customizer in 4.3 - Menus
6

8. © 2015 Rick Radko, r3df.com
Customizer in 4.3 - Site Icon
7

9. © 2015 Rick Radko, r3df.com
Why use the Customizer for options?
It provides a ready to use options framework:
 Native to WordPress
 No need to re-invent the wheel.
 Lots of built in controls.
 Can add custom controls.
 Now required for themes in wordpress.org repo.
 It’s the future for options.
I'm using it for:
 Custom theme & child theme options.
 Small plugins.
8

10. © 2015 Rick Radko, r3df.com
Plugin: Custom Login Page Customizer
9

11. © 2015 Rick Radko, r3df.com
Example Plugin: R3DF Copyright Message
10
wordpress.org/plugins/r3df-copyright-message

12. © 2015 Rick Radko, r3df.com
Adding a customizer option - 4 easy steps
1. Register your customizer set-up function.
2. Add a section.
3. Add settings.
4. Add controls to connect the settings to the
section.
11

13. © 2015 Rick Radko, r3df.com
Step 1. Register the customizer function
12

14. © 2015 Rick Radko, r3df.com
A gotcha for the 'customize_register' hook
From the codex:
"Important: Do not conditionally load your Customizer
code with an is_admin() check."
13

15. © 2015 Rick Radko, r3df.com
Step 2. Add a section
 $section_id - A unique ID for the section.
 $args: array
 title - the name of the section
 priority - (optional) controls display order of the
sections
 description - (optional) add descriptive text to the
section
14

16. © 2015 Rick Radko, r3df.com
Priorities for top level items
15
Priority (Order)
20
40
60
80
100
110
120
160 (default)

17. © 2015 Rick Radko, r3df.com
The section code for the plugin
Note:
 You will not be able to see the section until it
contains at least one control.
16

18. © 2015 Rick Radko, r3df.com
Step 3. Add setting(s)
 $setting_id - A unique ID for the setting.
 $args: array
 default - default value for the setting
 type - (optional)
types are 'option' or 'theme_mod'
type defaults to 'theme_mod'
Note:
 You will not be able to see the setting until it is
registered with a control.
17

19. © 2015 Rick Radko, r3df.com
Where are the values stored?
By default:
 Values are stored in the "wp_options" table.
 The option key depends on setting type:
 theme_mod:
Option key: theme_mods_{theme-name}
Array key (in the option): setting_id
 option:
Option key: setting_id
18

20. © 2015 Rick Radko, r3df.com
The settings code for the plugin
Note:
 The pseudo array notation, for the setting id, stores
the options as an array.
19

21. © 2015 Rick Radko, r3df.com
Step 4. Add control(s)
 $control_id - A unique ID for the control.
 If you set it to the value of a setting id, it will control
that setting. (instead of setting the settings arg)
 $args: array
 label - a label for the control
 description - a description below the label
 section - the section for the control
 type - basic types include:
text, checkbox, radio, select, dropdown-pages,
textarea…
20

22. © 2015 Rick Radko, r3df.com
The controls code for the plugin
21

23. © 2015 Rick Radko, r3df.com
The controls code for the plugin
22

24. © 2015 Rick Radko, r3df.com
The plugin display so far in customizer
23

25. © 2015 Rick Radko, r3df.com
The plugin - expanded
24

26. © 2015 Rick Radko, r3df.com
Where’s the copyright message?
25

27. © 2015 Rick Radko, r3df.com
Using saved option values
Setting type:
 theme_mod:
 option:
 Can use with standard WordPress options.
ie: convert existing plugin
26

28. © 2015 Rick Radko, r3df.com
The plugin's output code
27

29. © 2015 Rick Radko, r3df.com
The complete result in the customizer
28

30. © 2015 Rick Radko, r3df.com
The result on the frontend
29

31. © 2015 Rick Radko, r3df.com
Beyond the basics - Conditional actions
Conditional display – dependent on radio button 30

32. © 2015 Rick Radko, r3df.com
Beyond the basics - Transport
By default, when a customizer setting is changed:
 The preview is updated with a page refresh.
 This has a notable lag…
But, we can fix that…
31

33. © 2015 Rick Radko, r3df.com
Beyond the basics - Transport
Add some javascript…
…and the page will update “instantly”.
Note:
 Preview javascript is loaded on the
"customize_preview_init" action 32

34. © 2015 Rick Radko, r3df.com
Beyond the basics - Sanitizing values
Input data can be sanitized by adding callbacks to
the add_setting() definition:
 Built in WordPress functions can often be used.
 sanitize_key() checks that the data looks like an
internal identifier (key).
33

35. © 2015 Rick Radko, r3df.com
Beyond the basics - Panels
34
2 Items

36. © 2015 Rick Radko, r3df.com
Beyond the basics - Panels
35
New top level

37. © 2015 Rick Radko, r3df.com
Beyond the basics - Panels
36

38. © 2015 Rick Radko, r3df.com
Beyond the basics - Panels
 Panel with 2 sections
37

39. © 2015 Rick Radko, r3df.com
Beyond the basics - Modifying existing sections
 get_panel() for panels, get_setting() for settings, and
get_control() for controls
38
Section Id
title_tagline
colors
header_image
background_image
nav_menus
widgets
static_front_page
r3df_copyright_message_settings

40. © 2015 Rick Radko, r3df.com
Beyond the basics - Advanced controls
Advanced Controls:
 Color picker: WP_Customize_Color_Control()
 Media uploader: WP_Customize_Upload_Control()
 Image uploader: WP_Customize_Image_Control()
 Background image control:
WP_Customize_Background_Image_Control()
 Header image control:
WP_Customize_Header_Image_Control()
Custom controls:
 ottopress.com/2012/making-a-custom-control-for-
the-theme-customizer/
39

41. © 2015 Rick Radko, r3df.com
How does preview update without saving?
The customizer preview intercepts calls to:
 get_theme_mod
 get_option
Replaces them with the "live" content from the
customizer controls.
Note:
 This only seems to work on or after the action
"parse_request".
40

42. © 2015 Rick Radko, r3df.com
Learn More…
 codex.wordpress.org/Theme_Customization_API
 developer.wordpress.org/themes/advanced-topics/customizer-api/
 developer.wordpress.org/reference/classes/wp_customize_manager/
 ottopress.com/2012/how-to-leverage-the-theme-customizer-in-your-own-
themes/
 ottopress.com/2012/theme-customizer-part-deux-getting-rid-of-options-
pages/
 ottopress.com/2012/making-a-custom-control-for-the-theme-customizer/
 ottopress.com/2015/whats-new-with-the-customizer/
 gavick.com/blog/contextual-controls-theme-customizer
 gavick.com/blog/using-javascript-theme-customization-screen
 make.wordpress.org/core/2014/10/27/toward-a-complete-javascript-api-
for-the-customizer/
 make.wordpress.org/core/2015/07/27/site-icon/
41

43. © 2015 Rick Radko, r3df.com
Contact
Rick Radko
 email: wpinfo@r3df.com
 twitter: @r3designforge
Websites:
 r3df.com
 lumostech.training
Slides at:
 www.slideshare.net/r3df
42