Ari Stathopoulos 4:41 pm on December 30, 2019
Tags: color-alpha-package, ,   

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