kirki-framework/control-color

Color control for the Kirki Customizer framework.

v1.0.1 2021-12-29 13:22 UTC

This package is auto-updated.

Last update: 2023-01-29 03:26:01 UTC


README

This control extends control-react-colorful.

Table of Contents

Installation

To install this package use composer:

composer require kirki-framework/control-color:dev-nightly

NOTE: If you get errors with the package dependencies, please run the following first:

composer require kirki-framework/control-react-colorful:dev-nightly

Until Kirki v4.0 is released some of these dependencies may not have a tag released, so in the meantime the above will allow you to install and use everything. new \Kirki\Field\Color( [ 'settings' => 'my_control_setting_id', 'label' => esc_html__( 'My Color Control', 'textdomain' ), 'description' => esc_html__( 'A description here.', 'kirki' ), 'section' => 'my_section_id', 'default' => '#ff0000', 'choices' => [ 'alpha' => true, ], ] );

Usage

This package contains the control itself, as well as a simplified API for the WordPress Customizer, installed via the composer dependencies system.

Using the simplified API

new \Kirki\Field\Color(
	[
		'settings'    => 'my_control_setting_id',
		'label'       => esc_html__( 'My Color Control', 'textdomain' ),
		'description' => esc_html__( 'A description here.', 'kirki' ),
		'section'     => 'my_section_id',
		'default'     => '#ff0000',
		'choices'     => [
			'alpha' => true,
		],
	]
);

Using the Customizer API

/**
 * Register customizer settings and controls.
 *
 * @param \WP_Customize_Manager $wp_customize The Customizer object.
 */
function my_customize_register_function( $wp_customize ) {

	// Add setting.
	$wp_customize->add_setting(
		'my_control_setting_id',
		[
			'type'              => 'theme_mod',
			'capability'        => 'edit_theme_options',
			'default'           => '#0000ff',
			'transport'         => 'refresh', // Or 'postMessage'.
			'sanitize_callback' => [ '\Kirki\Field\ReactColorful', 'sanitize' ],
		]
	);

	// Add control.
	$wp_customize->add_control(
		new \Kirki\Control\Color(
			$wp_customize,
			'my_control_setting_id',
			[
				'label'       => esc_html__( 'My Color Control', 'textdomain' ),
				'description' => esc_html__( 'A description here.', 'kirki' ),
				'section'     => 'my_section_id',
				'choices'     => [
					'alpha' => true,
				],
			]
		)
	);

	// Add more settings...

	// Add more controls...

}
add_action( 'customize_register', 'my_customize_register_function' );

Arguments

mode

Likely, you'll almost never need this. The possible set for now is 'mode' => 'hue' which is to set the color picker to use the hue (only) mode.

choices

The choices argument can contain these values:

  • alpha (bool) — Will be ignored if form_component is defined
  • save_as (bool) — Will be ignored if form_component is defined
  • trigger_style (string)
  • button_text (string) — Only applied if trigger_style value is button
  • form_component (string) — Look at form_component choice for more detail.

Choices

alpha (bool)

The default is treated as false. If you want to show the alpha channel, then use 'alpha' => 'true' in inside choices argument. For example:

'choices' => [
	'alpha' => true
]

This alpha choice will be ignored if you define form_component inside choices argument.

save_as (string)

This is a new choice start from v4. Accepts 'string' (default) or 'array'. If you want to save the value as array, you can use 'save_as' => 'array'.

Example of usage:

'choices' => [
	'save_as' => 'array'
]

Example of result:

[
	'r' => 255,
	'g' => 255,
	'b' => 50,
	'a' => '0.7'
]

This save_as choice will be ignored if you define form_component inside choices argument.

trigger_style (string)

This trigger_style choice default value is input. If you want to use button as the trigger, set the trigger_style choice to button. Usage example:

'choices' => [
	'trigger_type' => 'button'
]

button_text (string)

This button_text choice will only be implemented if trigger_syle value is button.
Usage example:

'choices' => [
	'trigger_type' => 'button',
	'button_text'  => 'Select Color'
]

form_component

You can pass arguments to the react-colorful component using the choices argument in the control. The only required argument here is form_component.

And in the form_component argument you can define the type of control you want, using one of the the following:

  • HexColorPicker
  • RgbColorPicker
  • RgbStringColorPicker
  • RgbaColorPicker
  • RgbaStringColorPicker
  • HslColorPicker
  • HslStringColorPicker
  • HslaColorPicker
  • HslaStringColorPicker
  • HsvColorPicker
  • HsvStringColorPicker
  • HsvaColorPicker
  • HsvaStringColorPicker

Their value will be saved either as an array or as a string in database (depends on form_component value). For information about the arguments you can use, please refer to the react-colorful documentation.

Development

If you want to make changes to this control, you can edit the JS files in the src folder.

  • If you haven't installed the packages, then run npm install
  • After done editing, run npm run build

License

MIT License