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

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

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

Introduced as Theme Customizer in 3.4

Theme Customizer - WordPress 3.4

Theme Customizer - Evolution

Theme Customizer - Widgets & Panels

Customizer in 4.2

Customizer - Change themes

Customizer - Future

Custom Login Page Customizer

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.

Example Plugin: R3DF Copyright Message

wordpress.org/plugins/r3df-copyright-message

Example Plugin - Detail

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.

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.

The register code for the example plugin

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!!!

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

The section code for the example plugin

You will not be able to see the section until it

contains at least one setting.

Sections in 4.2 vs 4.3

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

The settings code for the example plugin

The pseudo array notation, for the setting id,

allows the options to be stored as an array.

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

The controls code for the example plugin

The customizer options

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

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.

The example plugin's output code

The output hooks in code

The result

Beyond the basics - Conditional actions

active_callback example

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

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.

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/

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

Contact

Rick Radko email: wpinfo@r3df.com twitter: @r3designforge

Websites: r3df.com lumostech.training

Slides at: www.slideshare.net/r3df

WordPress customizer: for themes and more

rick radko software

customizer function

customizer code

theme customizer wordpress

customizer future

customizer stuff

customizer setup function

theme customizer evolution

Technology

Customizing the WordPress Customizer

Wordpress Free Themes 2014

WordPress Auction Themes

Best Wordpress Themes 2014

WordPress Gallery Themes & Plugins

· Benefit from the WordPress Customizer WordCamp Antwerp....

WordPress Customizer

Choosing & Customizing WordPress Themes

Using Responsive WordPress Themes

WordPress Themes Demystified

Best Wordpress Video Themes

Best CrowdFunding WordPress Themes

How WordPress Themes Work

Modifying Wordpress Themes

Intro to WordPress Themes

WordPress Premium Themes