Read This First
The best tutorial I have found for understanding the Customizer API quickly is Narayan Prusty’s Getting Started with the WordPress Customization API (SitePoint, Feb. 2015). It only covers some basic concepts, but I found it to be extremely useful in wrapping my head around some concepts that were causing me to get lost in deeper articles.
[Each of these terms is used in the context of the Customizer, thus when reading “The Admin UI” it should be read contextually as “The [Customizer] Admin API.” This reduces redundancy, but if not taken note of here could cause confusion with other areas of WordPress outside the current context (e.g. the general UI).]
- Customizer – The Admin UI, but used generally to refer to the entire Customizer interface and underlying API.
- Options can be granted on a granular basis and contextual to what the user is previewing.
- Theme Modification API – CRUD.
- Theme Customization API – Add/Remove settings.
- The Customizer API is object-oriented, the main types of objects are:
- Panels – In the UI, top-level, contains sections, for organization.
- Sections – In the UI, contains settings, for organization.
- Settings – The back-end interface that handles connecting Controls to the db.
- Controls – UI interface for settings, allows users to interact with settings via intuitive UI.
- Theme Options – There have been, historically, a number of different ways to build theme options – but the official (canonical) way is now to use the Customizer API.
Each object is represented by a PHP class and all objects are managed by the Customize Manager object (WP_Customize_Manager), oftentimes instantiated as $wp_customize.
- The Customize Manager provides add_, get_, and remove_ methods for each Customizer object type (e.g. panels, sections, settings, controls).
There is a base WP_Customize_Control object, custom controls are essentially subclasses of the this base object. Several are built-in: color, upload, image, background image, header image.
Base Object / Class
This is the most generic object.
Color Picker Control
Media Control (Select / Upload Files)
Upload File Control
This appears to be for general file control.
- WP Codex: Class Reference/WP_Customize_Upload_Control
- WP Code Reference: WP_Customize_Upload_Control
Stores the URL of the image, use media control for image id.
- WP Codex: Class Reference/WP_Customize_Image_Control – Very bare bones (1/6/16).
- WP Code Reference: WP_Customize_Image_Control
Live Preview / Save / Sanitization
Settings are responsible for live-preview, saving, and sanitization of Customizer objects.
Primary Types of Settings
Settings can be saved primarily in two places.
One is as an option in the wp_options table. These are applied regardless of the active theme, thus themes should not add options.
Why do they exist? Because they can be appropriate when writing plugins.
The other is as a theme modification (theme_mods) and these are only active when the theme that created them is active.
Retrieving Theme Mods / Options
One uses get_theme_mod() and/or get_option() when retrieving a setting set in customizer.
The second value should be the default value of the field being pulled.
A control is the UI that is used by a user to select the value they desire to be saved for a specific setting.
The most important parameter is type, because this determines the type of UI that will be displayed.
WP includes a number of built-in types: text, checkbox, textarea, radio, select, dropdown-pages.
Core Section Priorities:
- Site Title & Tagline – title_tagline – 20
- Colors – colors – 40
- Header Image – header_image – 60
- Background Image – background_image – 80
- Navigation – nav – 100
- Widgets (Panel) – widgets – 110
- Static Front Page – static_front_page – 120
- default – 160
- “More than just grouping sections of controls, panels are designed to provide distinct contexts for the Customizer, such as Customizing Widgets, Menus, browsing themes, or perhaps in the future, editing posts.”
- Usually not necessary to utilize Panels, Sections are oftentimes sufficient.
Using AJAX for Faster Live Previews
To utilize AJAX you need to set the transport method for a setting to postMessage.
Bibliography / Further Reading
- Alex Mansfield. The WordPress Theme Customizer: a Comprehensive Developer’s Guide. ThemeFoundation, Nov. 2012.
- This article has been updated since 2012, but, unfortunately, when and what is not disclosed.
- Its stand-out feature is the depth it goes into sanitization callbacks.
- Narayan Prusty. Getting Started with the WordPress Theme Customization API. SitePoint, Feb. 2015.
- David Hayes. Making Themes More WYSIWYG with the WordPress Customizer. WPSHOUT!, April 2015.
- A useful article, includes a brief dive into creating custom classes.
- NARGA Editorial. Comprehensive Guide to make WordPress Theme Options with Customization API. NARGA, Sept. 2013.
- Rachel McCollin. The WordPress Theme Customizer. Smashing Magazine, March 2013.
- Scott Fennell. Getting Started with the WordPress Customizer. CSS Tricks, Dec. 2015.
- Useful, but some of his techniques are a bit different than those used elsewhere and may be confusing.
- Unique contribution is explanation of deregistering settings.
- WordPress Theme Handbook. “Theme Options – The Customizer API.”
On Custom Controls
- Afzal Hossain. Srizon Custom Controls. GitHub.
- Daniel Pataki. Creating Cool Custom Controls for the WordPress Theme Customizer. wpmudev, Nov. 2014.
- Denis Zoljom. WordPress Theme Customizer Extra Custom Controls. GitHub.
- A bundle of custom controls including multi input, sidebar dropdown, image select, checkbox switch, custom info., custom separator.
- Erik Ford. Add Custom Category Controls to WordPress. Aug. 2013.
- An article explaining how to build a custom category control.
- Appears to be the most robust manner of extending custom controls currently available.
- Includes following custom controls: editor, radio, checkbox, switch, code, repeater, radio image, color, radio-buttonset, text, typography, select control, number control, toggle, color-alpha, radio, slider, palette,dimension, select, textarea.
- Paul Lund. WordPress Theme Customizer Custom Controls. GitHub.
- A collection of custom controls built by Paul Lund.
- Search Results for “wordpress custom control” on GitHub.