Creating Customizer Options for Themes and Plugins

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

© 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

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)

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.

Theme Customizer - WordPress 3.4
4

Customizer in 4.3
5

Customizer in 4.3 - Menus
6

Customizer in 4.3 - Site Icon
7

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

Plugin: Custom Login Page Customizer
9

Example Plugin: R3DF Copyright Message
10
wordpress.org/plugins/r3df-copyright-message

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

Step 1. Register the customizer function
12

A gotcha for the 'customize_register' hook
From the codex:
"Important: Do not conditionally load your Customizer
code with an is_admin() check."
13

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

Priorities for top level items
15
Priority (Order)
20
40
60
80
100
110
120
160 (default)

The section code for the plugin
Note:
 You will not be able to see the section until it
contains at least one control.
16

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

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

The settings code for the plugin
Note:
 The pseudo array notation, for the setting id, stores
the options as an array.
19

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

The controls code for the plugin
21

The controls code for the plugin
22

The plugin display so far in customizer
23

The plugin - expanded
24

Where’s the copyright message?
25

Using saved option values
Setting type:
 theme_mod:
 option:
 Can use with standard WordPress options.
ie: convert existing plugin
26

The plugin's output code
27

The complete result in the customizer
28

The result on the frontend
29

Beyond the basics - Conditional actions
Conditional display – dependent on radio button 30

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

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

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

Beyond the basics - Panels
34
2 Items

35
New top level

36

 Panel with 2 sections
37

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

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

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

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

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

Creating Customizer Options for Themes and Plugins

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Was ist angesagt?

Was ist angesagt? (18)

Andere mochten auch

Andere mochten auch (20)

Ähnlich wie Creating Customizer Options for Themes and Plugins

Ähnlich wie Creating Customizer Options for Themes and Plugins (20)

Mehr von R-Cubed Design Forge

Mehr von R-Cubed Design Forge (8)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

Creating Customizer Options for Themes and Plugins