New color-alpha package available

A few months ago we started creating a new color-alpha package for themes that want to use a color picker in the customizerCustomizer Tool 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.

RGBA Colorpicker control screenshot

This control uses the react-color color picker, and can serve as an example of how developers can build reactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/.-based controls for the Customizer.
It is lighter than the default Customizer color picker scripts based on Iris, and there were further performance improvements – namely regarding the instantiation of the control. By default, color pickers get instantiated when the customizer loads. This control, however, will only get instantiated when the section containing it opens, significantly improving performance for themes that use many color pickers in the customizer.

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

Installation

You can find installation instructions in the repository’s readme file.

Usage

This is a control containing a JS template. As such, it should be whitelisted in the Customizer. To do that we can use the WP_Customize_Manager::register_control_type method:

add_action( 'customize_register', function( $wp_customize ) {
	$wp_customize->register_control_type( '\WPTRT\Customize\Control\ColorAlpha' );
} );

After the control is registered with the above snippet, we can use it in the customizer using the Customizer API:

use \WPTRT\Customize\Control\ColorAlpha;

add_action( 'customize_register', function( $wp_customize ) {

	// Add Setting.
	$wp_customize->add_setting( 'your_setting_id' , [
		'default'           => 'rgba(0,0,0,0.5)', // Use any HEX or RGBA value.
		'transport'         => 'refresh',
		'sanitize_callback' => 'my_custom_sanitization_callback'
	] );

	// Add Control.
	$wp_customize->add_control( new ColorAlpha( $wp_customize, 'your_setting_id', [
		'label'      => __( 'My Color', 'mytheme' ),
		'section'    => 'my_section',
		'settings'   => 'your_setting_id',
	] ) );
} );

Sanitization

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.

Available filters

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_url filterFilter Filters 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 URLURL A 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 pluginPlugin A 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) accessibilityAccessibility Accessibility (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:

$wp_customize->add_control( new ColorAlpha( $wp_customize, 'your_setting_id', [
	'label'    => __( 'My Color', 'mytheme' ),
	'section'  => 'my_section',
	'settings' => 'your_setting_id',
	'choices'  => [
		'save_as' => 'array',
	]
] ) );

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:

$text_color = $value['a11y']['maxContrastColor'];

Get readable color from background color:

$color = $value['a11y']['readableContrastingColorFromWhite'][0];
if ( $value['isDark'] ) {
	$color = $value['a11y']['readableContrastingColorFromBlack'][0];
}

Get a complementary color

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 CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site.:

$h = ( $value['h'] > 180 ) ? $value['h'] - 180 : $value['h'] + 180;
$s = $value['s'];
$l = $value['l'];
$a = $value['a'];
$color = 'hsla(' . $h . ',' . $s . '%,' . $l . '%,' . $a . ')';

You can use the same logic to build color triads or your own custom palette from a single control by rotating the hue (usually by 30, 45, 60, 90, 120, or 180 degrees)

Contributing

This control is developed on its own GitHub repository. All contributions are welcomed there.

#color-alpha-package, #customizer-api, #open-source

Theme Sniffer v1.1.0 and WPThemeReview v0.2.0 release

The update of the Theme Sniffer plugin and the WPThemeReview coding standards is out 🎉

Theme SnifferTheme Sniffer Theme Sniffer is a plugin utilizing custom sniffs for PHP_CodeSniffer that statically analyzes your theme and ensures that it adheres to WordPress coding conventions, as well as checking your code against PHP version compatibility. The plugin is available from GitHub. Themes are not required to pass the Theme Sniffer scan without warnings or errors to be included in the theme directory. is a pluginPlugin A 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 utilising custom sniffssniff A module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food. for PHP_CodeSniffer that statically analyses your theme and ensures that it adheres to WordPress coding conventions, as well as checking your code against PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. version compatibility.

WPThemeReview is the official Theme Review Team coding standard used for checking the themes using PHP_CodeSniffer (PHPCSPHP Code Sniffer PHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS.).

Both are used as helpful tools during the theme review process (not a requirement).

In the Theme Sniffer update we’ve done some bigger changes, including

  • Added sniffsniff A module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food. codes that can be copied for easier whitelisting of the false issues
  • Added readme validator
  • Added Screenshot validator
  • Added required files checks
  • Added checks for coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. minimum PHP version
  • Added a license validator
  • Updated WPThemeReview coding standards to the 0.2.0 version
  • Moved JS checking to esprima
  • Moved installation error to admin notice
  • Validation improvements
  • Fixed annotation issue – the ingore annotation checkbox worked counter to what it should
  • Fixed cross-env issue for development on Windows machines
  • Minor grammar fixes
  • Minor visual fixes

A lot of new this have been added and I’d like to thank @timph for making an awesome contribution to the plugin.
I’d also like to thank all other awesome contributors. Your work is really appreciated.

In the WPThemeReview update we’ve added some new sniffs, updated few rulesets and fixed some old sniffs to minimize the false positives. You can check out the full changelog here.

I’d also like to thank @jrf for helping out with the standards. Her expertise is invaluable to us.

Roadmap

The development of the Theme Sniffer and standards continues, and the roadmap that I had in mind, for the Theme Sniffer, was to

  1. Write complete integration test suite
  2. Improve on the accessibilityAccessibility Accessibility (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) of the admin area
  3. Refactor the plugin to add php-di for dependency injection
  4. Refactor the plugin to make the codebase more manageable
  5. Refactor some JS to remove jQuery dependency, as it’s not really needed and all the JS can be written in vanilla JS
  6. Add the features mentioned in the issues

For the standards, we need to decide on some open issues, then make a roadmap for implementing other sniffs.

The plugin is actively developed on Github, so if you wish to contribute you can start there. Also, if you find any issue with the plugin, feel free to open an issue on the repository.

You can find an entry in the handbook about the usage and some clarification regarding the sniff results interpretation.

The standard is also developed on Github, contributions are welcomed.

Call for contributors

We need your help. While I’d love nothing more than to work on this and other TRT open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. projects, I just don’t have enough time to work full time on it (which impacts the releases and updates).

So if you have experience with modern object oriented PHP and want to help develop an awesome tool I’d be happy to help you with the onboarding. Also, writing documentation, doing some quality assurance issues, working on design improvements (a11yAccessibility Accessibility (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)) and solving some other issues is also very welcomed.

#open-source, #plugin, #theme-sniffer

Feature Projects: Customize Section Button and Autoload

Today, I’m happy to announce the official 1.0 release of our first two feature projects.

If you haven’t been following along, the team decided to build out some features that many themes build in very different ways. The idea is to bring some standardization for these features for authors, reviewers, and end users in the case of packages with a UIUI UI 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.. It also means that all theme authors will have access to these tools and not have to worry about building them in-house.

Note: PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. 5.6+ is a requirement for the current packages. This means your theme must be built for WordPress 5.2+ or that you’ll need to gracefully fail if supporting older versions.

Customize Section Button

Screenshot of the customize section button in the WordPress theme customizer.
Screenshot of the Customize Section Button

This project provides a method of adding a link/button in the customizerCustomizer Tool 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.. The primary use case for it will likely be to add an upsell link, but I could see it being used for something like pointing a user to documentation. It’s pretty straightforward to use and works like any other customizer section.

Autoload

The Autoload project is a package for autoloading any classes that we create, such as the above-mentioned Customize Section Button project. It allows you to define namespaces and the directory path(s) of where to find classes.

We view this project as a stepping stone toward getting theme authors to use a proper dependency manager such as Composer and its autoloading feature. We also strongly recommend following the Composer Autoloading Optimization Guide. Seriously, use Composer if you’re ready for it or already using it.

I think we should also view this project as call for the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. developers to implement a proper autoloading feature into WordPress itself. Such a feature would be far more efficient and provide a standard for both theme and pluginPlugin A 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 authors to follow.

Are these packages required?

This question has come up a few times, so I wanted to go ahead and address it now. The short answer is that, no, they are not currently required.

The long answer is that I don’t know what the team may decide in the future. There may be projects where the team will say, “If you want to implement this feature, use this particular package.” It’d certainly help streamline some of the review process, but there are things to consider other than the review process.

My goal is to get the TRT and theme authors working together to build solutions. If we build good solutions, I’d hope that theme authors would naturally move toward using them because it ultimately saves them time and resources. I still think the question of whether a particular package should be required is premature. Let’s build the solutions together first.

Next projects

The next projects are likely going to be a set of standard theme template hooksHooks In 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. and something to tackle admin notices. These are a little bigger than the first two projects and will likely need more community involvement. We’ll try to get repos up for them soon so that we can begin discussions.

#open-source, #projects, #trt

Feature Packages Update

A couple of weeks ago, we set forth a theme feature packages proposal. The team got loads of good feedback. As the current lead for the proposal, I was trying to best think how to kick-start such a project. So, I decided to just tackle some low-hanging fruit that would provide a better idea of what this project is about.

The idea is to create “drop-in” packages that theme authors can use to handle some common features. This would help standardize some of the code we’re seeing.

I created two new packages, both of which I had some existing code to pull from. This provided us with a starting point.

Neither of these projects are at their official 1.0.0 stage. I’d like to get there this week or next at the latest. They need a code review and testing. So, this is an open call to check those projects out and leave any feedback.

Autoload Package

For feature packages, theme authors need a way to autoload any PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. classes that we provide. I’d strongly recommend Composer instead of this package.

However, not all theme authors are ready to make that leap yet. If you fall into this camp, we put together a small PSR-4-compliant autoloader. This is a foundational package that will allow you to use any other packages that we create. You could even use it for autoloading your own theme classes if you choose to do so (assuming they follow the PSR-4 autoloading standard for class and folder names).

See the Autoloader repository →

Customize Section Button Package

This is a customizerCustomizer Tool 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. section that allows theme authors to create a link/button to any URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org. The idea behind this was primarily for pro/upsell links from the customizer. However, we kept it generic enough to handle any link and not limit it to only upsells.

See the Customizer Section Button repository →

Proposed Packages

There were a number of proposed ideas in the previous post’s comments and on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.. I’m going to list most of them with feedback for further discussion.

Standard Template HooksHooks In 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.

This is a proposal to fork the original Theme Hook Alliance project or create something similar. The idea is to create a set of standard theme hooks that plugins and child themes can utilize.

Customizer Framework

This is probably thinking too big. We should break this down and look at tackling individual problems. What I mean by this is that we should build custom sections, controls, and/or settings classes that theme authors need as individual projects. One such example is the above “Customize Section Button,” which solves the issue of adding a custom “pro” link to the customizer.

If we have enough smaller packages at some point in the future, it’d be super simple to create a “WPTRT Customize Framework” that simply tells Composer to include all of our individual packages if that was desirable. However, I tend to lean toward themes only including code that they’re using.

Appearance > Theme Page

The idea here is to create a standardized Appearance > ThemeName page in the WordPress admin. My worry here is that this is far too theme-specific to do anything more than an abstract class that calls add_theme_page() and outputs a “template”.

I’d love to hear more about what we could standardize with this.

Breadcrumbs

Not a bad idea. Not a bad idea at all.

Breadcrumbs are extremely tough to build and build right. I cringe almost anytime I see a custom breadcrumbs implementation because I see all the inherent flaws. I’ve built my own breadcrumbs system, and it’s quite a beast because it handles 100s of different scenarios.

This is an extremely complex problem to solve and would take a dedicated group of developers to tackle it.

Sliders and Sections

The proposal here, if I’m not mistaken, is for a standard customizer package that allows users to select exists posts, pages, etc. that could then be used in something like a slider or group of sections on the front end.

I think this could work as a package. Probably something along the lines of a repeatable post drop-down.

Mobile Navigation

A couple of different mobile navigation ideas were proposed. I’m not the best person to lead this charge. If there’s someone with the right CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site./JS skills to make a solution that could work as a drop-in for themes, this would be worth exploring.

Color Control with Transparency

A color control for the customizer with an alpha transparency slider. Sounds like a cool idea. I’d actually love to see an implementation of this.

CSS Custom Properties

I didn’t quite grasp what the actual proposal for this package was.

Nav Menu Walker

With this, I’m also not sure what the proposal is other than making sure theme authors test their themes.

#open-source, #projects, #trt