We are a group of volunteers who review and approve themes submitted to be included in the official WordPress Theme directory.
We do license, security, and code quality reviews.
We help build and maintain default themes.
The primary focus of the team is to help theme authors transition to blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.-based themes.
A few months ago we started creating a new color-alpha package for themes that want to use a color picker in the customizerCustomizerTool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. capable of handling rgba colors with opacity.
During the course of these months the concept we were working on evolved and today we’re glad to announce it’s finally available for themes.
By default, the control works just like any other control and saves a string with the selected color. The format of the saved value will depend on the opacity of the selected color. If the color is completely opaque, then it will save a HEX value (#000000). If the selected color is not completely opaque (has an alpha value smaller than 1) then the value will be saved as RGBA (rgba(0,0,0,0.9)).
All controls should be sanitized in the customizer. Since the color-alpha control can save either a hex or an rgba value, we built a custom sanitization callback you can use.
By default, the control will work out of the box for any plugins and themes installed in wp-content/themes and wp-content/plugins respectively. If however, the control is not inside the wp-content folder, then you can use the wptrt_color_picker_alpha_urlfilterFilterFilters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. to define its URLURLA specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org. You can see an example of that in the repository’s readme file.
Everything described above is the default behavior of the control. However, if developers wish, this control can handle a lot more. We added the option to save the value as an array and expose more tools that you can use.
If you want to automate things and do more advanced color calculations, continue reading the section below.
Saving value as an array
Though the default behavior of the control is to save a simple string, developers have the option to save the value as an array. The saved array contains the color properties as well as some extra items that can be used to enhance a theme’s (or pluginPluginA plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party’s) accessibilityAccessibilityAccessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility).
To change the behavior of the control and make it save an array instead of string, users can add 'save_as' => 'array' under the control’s choices:
The value saved will then have the following format:
'r' => 107, // Red.
'g' => 55, // Green.
'b' => 119, // Blue.
'h' => 289, // Hue.
's' => 37, // Saturation.
'l' => 34, // Lightness.
'a' => 0.82, // Alpha
'hex' => '#6b3777', // The HEX code of the color (alpha = 1)
'css' => 'rgba(107,55,119,0.82)', // The CSS value of the selected color.
'a11y' => [ // An array of accessibility-related properties.
'luminance' => 0.0719,
// Contrast with white (value 0 - 21).
'distanceFromWhite' => 8.613,
// Contrast with black (value 0 - 21).
'distanceFromBlack' => 2.438,
// Maximum contrasting color. Use this to get the text-color
// if the colorpicker is used to select a background-color.
'maxContrastColor' => '#ffffff',
// Readable text-colors on white background preserving the hue.
// The 1st value has a minimum contrast of 7:1 with white.
// The 2nd value has a minimum contrast of 4.5:1 with white.
'readableContrastingColorFromWhite' => [ '#6b3777', '#6b3777' ],
// Readable text-colors on black background preserving the hue.
// The 1st value has a minimum contrast of 7:1 with black.
// The 2nd value has a minimum contrast of 4.5:1 with black.
'readableContrastingColorFromBlack' => [ '#bc83c7', '#a458b5' ],
// True if the color is dark.
'isDark' => true
The saved value contains all the properties needed to automate a lot of processes, and we hope it will encourage developers to do more things without the need to provide multiple controls.
Sanitizing the control when saving an array
If you choose to save the value as an array, we have an example sanitization callback you can use in the repository.
Using the array value
You can use these properties however you like. Below are some simple examples:
Get the cssvalue
This will get the value that the control would normally save if not saving as an array:
$rgba = $value['css']
Get the text-color from a background-color
Using the code below we can get the optimum text-color when our selected color is used for the background. Text color, in this case, will be either #000000 or #ffffff:
Here we’re using the saved color properties. We’ll rotate the hue by 180 degrees, and build an hsla color that can then be used in our CSSCSSCSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site.:
One of the things we’ve been discussing is setting up a customizerCustomizerTool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. snippet repository on the TRT GitHub account. Nothing is exactly set in stone just yet, but we wanted to gather some feedback before moving forward.
Should this be a library of non-coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. Controls?
Should it contain other snippets unrelated to controls?
How should things be organized?
What would you like to see?
These are all really broad questions, but it’s important to get a feel for what we need to do first if we decide to go ahead with this project.
We really need to start from square one and decide on exactly what we’d like the repo to be. From there, we can decide how to organize it. Then, we can put cool stuff in it.
One of the things that TRT has been doing over the past several months is striving to make education a top priority. We’ve got some awesome things in the pipeline (look out for design and accessibilityAccessibilityAccessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) resources soon).
Today’s topic is about utilizing the Customization APIAPIAn API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. (i.e., the theme customizerCustomizerTool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings.). Over the past week I’ve been gathering links to various tutorials to share with theme authors. There’s actually quite a bit that’s been written on the customizer. I thought it’d be helpful to consolidate some of these into one place.
This list is just a sampling of what’s out there. It also gives us an idea of what hasn’t been written about so that we can strive to provide more examples.
Of course, the best place to start is the developer handbook right here on WordPress.orgWordPress.orgThe community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/. So, dive into the Customizer API docs before anything.
General and Basic Tutorials
The following tutorials are mostly overviews and general tutorials on the basics of working with the customizer. A few dive into some more advanced topics, but for the most part, they’re good for getting acquainted with the customizer.
A few days ago, Chip Bennett wrote a good tutorial on the APIs related to theme options and broke down how those APIs can/should be used depending on the context. If anyone can really go in depth with theme options, it’s Chip. I’m hoping we see more from him on theme options in the future. I highly encourage reading his post to make sure you have the foundation you need.
In this post, I want to cover a question that has been popping up, particularly about the Theme Mods vs. Settings and which to use.
Essentially, we allow three different methods of handling theme options on the repository (technically, there are other methods, but we allow three):
CustomizerCustomizerTool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings.APIAPIAn API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. + Theme Mods
Customizer API + Settings API
Theme options page created with the Settings API
The customizer is so much easier to use and requires a lot less code. It’s something I strongly recommend. It’s also what I’ll be focusing on as I write more about theme options. This post is going to focus on whether you should use the Theme Mods API or the Settings API for storing options.
The thing many theme authors get hung up on is that theme mods are saved on a per-theme basis. So, this means when you switch child themes, any theme mod options will need to be saved again for the new child themeChild themeA Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your theme. https://developer.wordpress.org/themes/advanced-topics/child-themes/.. Sometimes, users might even see this as “losing their settings”.
This is both a blessing and a curse. I love it because it allows my users to have seasonal or holiday child themes. Imagine you wanted to have a child theme specifically for the Christmas season with its own color scheme. It’s nice to be able to change those color options just for the Christmas child theme.
What happens when you switch back to your regular theme in January? Well, it still has all of its unique options saved for it. There’s no work involved except for switching child themes.
The other nice thing is that coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. WP has hooksHooksIn WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. already built in for each new theme mod you create. That’s very nice for child theme authors who want to quickly filterFilterFilters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. options in the parent theme.
I’m less of a fan of the Settings API because it means that an option is saved based on the parent theme. The great thing about it is that users only have to save options once and not save them again if they switch child themes (technically, you can get around that if anyone wants me to explain the code).
Going back to the Christmas theme example: What happens when you switch to a Christmas child theme? In this scenario, you’d have to change your colors. Then, you’d have to change them again when switching back to your non-holiday child theme.
However, not all theme options need to be changed when a user switches child themes. Some options make more sense to stay the same, regardless of child theme.
What about a combination?
Actually, you can use a combination of both the Theme Mods API and Settings API with the customizer. It’s not an either/or thing. That’s just another example of its awesomeness. I even encourage this practice in some situations.
I imagine things like colors and fonts would generally make more sense as theme mods. But, an option to either show excerpts or content on the front page might be better served via the Settings API.
Each option should really be given this consideration rather than blindly doing one or the other.
There seems to be a great deal of confusion regarding the various APIs involved with Theme options, especially regarding the interactions among those APIs. This confusion is obvious in discussions involving the CustomizerCustomizerTool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings.. This post will attempt to explain the various APIs and how they work together.
The first thing to understand is the various interactions with options: storing options in the database, retrieving options from the database, and user configuration of options.
Storing and Retrieving Options
WordPress has two APIs for storing and retrieving Theme options: the Options API and the Theme Modification (Theme Mods) API. The Options APIAPIAn API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. is the “granddaddy” API, used by coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. and Plugins, as well as Themes. The Theme Mods API is a Theme-specific API.
The Options API uses the add_option() and update_option() functions to store options to the database, and get_option() to retrieve options from the database. The Theme Mods API uses the set_theme_mod() to store options to the database, and get_theme_mod() and get_theme_mods() to retrieve options from the database. Neither API deals with user configuration (e.g. Settings pages) of options.
User Configuration of Options
There are essentially three ways to allow users to configure Theme options: a Settings API-generated settings page, a custom settings page, and the Customizer API. Both a settings page and the Customizer display options retrieved by either the Settings API or the Theme Mods API, then return user-configured settings to that same API for storage in the database.
(Note: where the Theme Review Guidelines formerly recommended using the Settings API, that recommendation applied to using the Settings API to generate the settings page, rather than the Theme creating a custom settings page. That recommendation has been superseded by the recommendation to use the Customizer.)
The Settings API includes a robust set of functions to generate a Settings page, but is missing some key elements such as default markup for settings fields, and standard sanitization/validation based on option data type. This void is frequently filled by the various option framework libraries available. Using such frameworks avoids the necessity of the Theme developer to roll their own code. These frameworks generally also handle the sometimes complex callback structure needed to implement the Settings API fully. (And no joke; fully implementing the Settings API is so complex that I wrote a ten-page tutorial on it a few years ago.)
Until the Customizer, the only other option was a completely custom Theme settings page. These used to be all the rage (and can still be found in many options frameworks), and were promoted as a Theme “feature”. All they really did was add a non-core UIUIUI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. and increase the learning curve for Theme developers and users alike. That’s why the Theme Review Guidelines used to recommend use of the Settings API to generate Theme settings pages.
Now, for Themes that opted to use the Theme Mods API, a custom Theme settings page was the only option. The Theme Mods API is, overall, probably a better and easier API to understand and to use – but it did not include an API for creating a settings page.
Now, a third option exists: the Customizer.
It is important to keep in mind here that the Customizer is not an API for storing or retrieving settings; it is an API for user configuration of settings. It is not a replacement for either the Settings API or the Theme Mods API for storing/retrieving options; it is a replacement for Theme settings pages. The Customizer does not store options to or retrieve options from the database. It merely displays options retrieved by either the Theme Mods API or the Settings API, and returns settings to either the Theme Mods API or the Settings API for storage in the database.
This is a very important distinction to remember, because, while the Customizer defaults to using the Theme Mods API, it can be used with either the Theme Mods API or the Settings API. This flexibility is important for existing Themes as well as for new Themes. Developers of existing Themes that use the Settings API, and who want to migrate away from settings pages and toward use of the Customizer can do so quite easily. And Developers of new Themes that want to take advantage of the Customizer from the beginning can do so just as easily.
Theme Mods API and Options API are used to store/retrieve options
Settings pages and the Customizer are used to allow users to configure options
The Customizer can replace a Settings page and the Settings API, but cannot replace either the Theme Mods API or the Options API
The Customizer can be used on top of either the Theme Mods API or the Options API
Themes that currently use the Settings API, either directly or using an options framework library, can use the Customizer without changing any of the underlying options code already in use
Themes that currently use a Settings page with the Settings API can add Customizer support without impacting or removing the current Settings page
New Themes are recommended to use the Customizer with the Theme Mods API