wordpress customizer: for themes and more
TRANSCRIPT
r3df.com lumostech.training
Rick Radko
“WordPress Customizer: For Themes and More”
WordCamp Montreal July 4th, 2015
Slides at: slideshare.net/r3df
© 2015 Rick Radko, r3df.com
What's this talk about?
This talk: Is an overview to the using the customizer function
in WordPress plugins or themes. Goals: Demonstrate that it is easy to code an option. Encourage you to try it.
For code examples, I'm going to use a plugin I created: wordpress.org/plugins/r3df-copyright-message
1 Slides at: slideshare.net/r3df
© 2015 Rick Radko, r3df.com
A little bit about me
Rick Radko 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.
Lead organizer of: WordCamp Ottawa 2013, 2014, 2015. The Ottawa WordPress Group.
2 Slides at: slideshare.net/r3df
© 2015 Rick Radko, r3df.com
Introduced as Theme Customizer in 3.4
3
© 2015 Rick Radko, r3df.com
Theme Customizer - WordPress 3.4
4
© 2015 Rick Radko, r3df.com
Theme Customizer - Evolution
5
© 2015 Rick Radko, r3df.com
Theme Customizer - Widgets & Panels
6
© 2015 Rick Radko, r3df.com
Customizer in 4.2
7
© 2015 Rick Radko, r3df.com
Customizer - Change themes
8
© 2015 Rick Radko, r3df.com
Customizer - Future
9
© 2015 Rick Radko, r3df.com
Custom Login Page Customizer
10
© 2015 Rick Radko, r3df.com
Why use the Customizer?
It provides a ready to use options framework: No need to re-invent the wheel. Lots of built in "controls". Color pickers, image & files uploads, page lists.
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.
11
© 2015 Rick Radko, r3df.com
Example Plugin: R3DF Copyright Message
12
wordpress.org/plugins/r3df-copyright-message
© 2015 Rick Radko, r3df.com
Example Plugin - Detail
13
© 2015 Rick Radko, r3df.com
Lets see how to do it - 4 easy steps
1. Register your customizer set-up function. A place to put all the customizer stuff.
2. Add sections to the registered function. Sections hold the settings.
3. Add settings to the registered function. Settings define how the options will be saved.
4. Add controls to the registered function. Controls change the settings.
14
© 2015 Rick Radko, r3df.com
1. Register the customizer function
The function is passed an object, $wp_customize, which is used to create sections, settings and controls.
This function and add_action can be placed in functions.php or your main plugin file.
15
© 2015 Rick Radko, r3df.com
The register code for the example plugin
16
© 2015 Rick Radko, r3df.com
A 4.1+ gotcha for the 'customize_register' hook
From the codex: "Important: Do not conditionally load your Customizer code with an is_admin() check."
Your customizer options won't display properly!!!
17
© 2015 Rick Radko, r3df.com
2. Add section(s) for your settings
$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
18
© 2015 Rick Radko, r3df.com
The section code for the example plugin
You will not be able to see the section until it
contains at least one setting.
19
© 2015 Rick Radko, r3df.com
Sections in 4.2 vs 4.3
20
© 2015 Rick Radko, r3df.com
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'
You will not be able to see the setting until it
contains at least one control. 21
© 2015 Rick Radko, r3df.com
Where are the values stored?
Options 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
22
© 2015 Rick Radko, r3df.com
The settings code for the example plugin
The pseudo array notation, for the setting id,
allows the options to be stored as an array.
23
© 2015 Rick Radko, r3df.com
4. Add control(s)
$control_id - A unique ID for the setting. $args: array section - the section for the control settings - the setting that the control changes label - a label for the control type - basic types include: text, checkbox, radio, select, dropdown-pages,
textarea priority - sets the display order of the controls
24
© 2015 Rick Radko, r3df.com
The controls code for the example plugin
25
© 2015 Rick Radko, r3df.com
The customizer options
26
© 2015 Rick Radko, r3df.com
Using saved option values
Accessing the values depends on your setting type: theme_mod:
option:
can use with existing options ie: to use with existing plugin
27
© 2015 Rick Radko, r3df.com
Another potential gotcha!
User may not get the settings behaviour they expect: If, for example, you have a checkbox which
defaults to checked: Users will see the setting working with the default
when they view the preview. (so they don't change any settings)
BUT if they don't change your settings, They may NOT be saved!! (unless they make changes to other settings and save)
Need to make sure your code handles defaults if settings are not saved.
28
© 2015 Rick Radko, r3df.com
The example plugin's output code
29
© 2015 Rick Radko, r3df.com
The output hooks in code
30
© 2015 Rick Radko, r3df.com
The result
31
© 2015 Rick Radko, r3df.com
Beyond the basics - Conditional actions
32
© 2015 Rick Radko, r3df.com
Beyond the basics - Conditional actions
active_callback example
33
© 2015 Rick Radko, r3df.com
Beyond the basics - Modifying existing sections
You can of course modify existing customizer options. Built-in section id’s: Site Title & Tagline: title_tagline Colors: colors Header Image: header_image Background Image: background_image Navigation: nav Static Front Page: static_front_page
Also get_setting() and get_control() 34
© 2015 Rick Radko, r3df.com
Beyond the basics - Transport
By default, when a customizer setting is updated, the preview is updated with a page reload. This has a notable lag
If you add the transport argument to the add_setting call: (and add all the needed javascript)
The page will update “instantly”.
35
© 2015 Rick Radko, r3df.com
Beyond the basics - Sanitizing values
Input data can be sanitized by adding callbacks to the setting definition: The argument “sanitize_callback” adds a callback
to sanitize the input values for the setting. The argument “sanitize_js_callback” adds a
callback to sanitize the output to the javascript code for the preview. Should only be needed in special cases.
36
© 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/
37
© 2015 Rick Radko, r3df.com
Learn More…
codex.wordpress.org/Theme_Customization_API developer.wordpress.org/themes/advanced-topics/customizer-api/ ottopress.com/2012/how-to-leverage-the-theme-customizer-in-your-own-
themes/ http://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/ www.gavick.com/blog/contextual-controls-theme-customizer
38
© 2015 Rick Radko, r3df.com
Contact
Rick Radko email: [email protected] twitter: @r3designforge
Websites: r3df.com lumostech.training
Slides at: www.slideshare.net/r3df
39