WordPress customizer: for themes and more

r3df.com lumostech.training

Rick Radko

“WordPress Customizer: For Themes and More”

WordCamp Montreal July 4th, 2015

Slides at: slideshare.net/r3df

http://www.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

https://wordpress.org/plugins/r3df-copyright-message/



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

http://lumostech.training/

http://2013.ottawa.wordcamp.org/

http://2014.ottawa.wordcamp.org/

http://wpottawa.org/



Introduced as Theme Customizer in 3.4

3


Theme Customizer - WordPress 3.4

4


Theme Customizer - Evolution

5


Theme Customizer - Widgets & Panels

6


Customizer in 4.2

7


Customizer - Change themes

8


Customizer - Future

9


Custom Login Page Customizer

10


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


Example Plugin: R3DF Copyright Message

12

wordpress.org/plugins/r3df-copyright-message

https://wordpress.org/plugins/r3df-copyright-message/


Example Plugin - Detail

13


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


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


The register code for the example plugin

16


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


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


The section code for the example plugin

You will not be able to see the section until it

contains at least one setting.

19


Sections in 4.2 vs 4.3

20


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


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


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


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


The controls code for the example plugin

25


The customizer options

26


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


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


The example plugin's output code

29


The output hooks in code

30


The result

31


Beyond the basics - Conditional actions

32


Beyond the basics - Conditional actions

active_callback example

33


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


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


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


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

http://codex.wordpress.org/Class_Reference/WP_Customize_Color_Control

http://codex.wordpress.org/Class_Reference/WP_Customize_Upload_Control

http://codex.wordpress.org/Class_Reference/WP_Customize_Image_Control

http://codex.wordpress.org/index.php?title=Class_Reference/WP_Customize_Background_Image_Control&action=edit&redlink=1

http://codex.wordpress.org/index.php?title=Class_Reference/WP_Customize_Header_Image_Control&action=edit&redlink=1

http://ottopress.com/2012/making-a-custom-control-for-the-theme-customizer/



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

http://codex.wordpress.org/Theme_Customization_API

https://developer.wordpress.org/themes/advanced-topics/customizer-api/

http://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/

http://ottopress.com/2012/theme-customizer-part-deux-getting-rid-of-options-pages/


http://ottopress.com/2015/whats-new-with-the-customizer/

https://www.gavick.com/blog/contextual-controls-theme-customizer


Contact

Rick Radko email: [email protected] twitter: @r3designforge

Websites: r3df.com lumostech.training

Slides at: www.slideshare.net/r3df

39

mailto:[email protected]

https://twitter.com/r3designforge

http://r3df.com/




WordPress customizer: for themes and more

Technology

rick radko software

customizer function

customizer code

theme customizer wordpress

customizer future

customizer stuff

customizer setup function

theme customizer evolution