Once installed, the addon package can be used in two ways.

A. Modify code to load the helper from this package.

Where you would previously have written php code:

$ch = Loader::helper('form/color');

You now write:

$ch = Loader::helper('spectrum_color', 'jl_spectrum_color_picker');

The actual call to output the color picker control is unchanged.

B. Install an override of the core helper

Alternatively, you could install an override of the core color helper by copying

site_root_/packages/ jl_spectrum_color_picker/helpers/form/color.php

to

site_root/ helpers/form/color.php

Loading Assets

In both of the above cases, you will also need to load the applicable assets. Here you have 3 choices:

1. Load globally

To load the color picker assets for all pages, in config/site.php.

define('LOAD_SPECTRUM_ASSETS_ON_START', true);

2. Load assets through the helper

Within a controller, typically in an on_page_view() or in an on_start() event handler and perhaps by the intermediary of an on_before_render event handler, call the asset loading method provided with the helper.

$ch = Loader::helper('spectrum_color', 'jl_spectrum_color_picker');
$ch->addHeaders($controller);

While the method is called addHeaders(), JavaScript is actually loaded in the footer. 

The $controller variable in the above example must be an instance of a controller that supports addHeaderItem() and addFooterItem(). In a block controller, you could usually pass $this to addHeaders().

3. Load assets individually

You can also load assets individually, using code based on that within the addHeaders() method.

4. Just be lazy

You also have the option of simply being lazy and ignoring the above. The JavaScript in the helper will check for its assets and lazy load them if neccesary.

Hazards

If you simply use the helper directly from code written to work with it, there are no dangers in using this color picker. For RGBA formatted color strings you should allow 26+ characters of storage. This is the recommended method of use and what classes this addon as 'Expert'.

If you modify existing code that was written to handle simple 6 or 7 character hexadecimal color strings, the danger is that something inside that will not be coded to handle RGBA strings. It could be that database fields are too small for 26+ characters to be saved. It could be that code that interprets the colors expects 6 character hex rather than RGBA. This could result in database errors, php code errors and page formatting errors.

If you install the override for the core color helper, the dangers are the same but multiplied many times because you will have no control of what gets subjected to the longer character strings and unexpected color formats. If it were not for the above recommended method of use, installing the override would make this addon 'Bleeding Edge'.

To date, no breaking problems have been found if this override is installed. However, the Customise Themes dashboard page continues to do its own thing with the old color picker.

Uses and tips

This color picker has been developed in association with other marketplace packages I have on the way and extensively tested with them. It is safe to use as a basis for new addon development. I recommend placing a dependancy on this addon package and loading the picker from this package rather than copying key files into your own addon package. That way you will not run a future risk of namespace clashes and will benefit immediately from any fixes and enhancements.

On test sites I have installed the provided override for the core helper and found it to work correctly with block design.

When installed, this color picker is completely ignored by the dashboard Customize Theme page because that page interacts with the existing color picker JavaScript directly.

Color picker extension

In addition to adding opacity to provide RGBA color picking, this helper can pass on to the Spectrum JavaScript any of the options it accepts. Please see http://bgrins.github.io/spectrum/

Methods are provided in the helper for setting the options and, in particular, for setting up a color palette.

Please see the comments in the code of spectrum_color.php for details.