Once installed, the addon package can be used in two ways.
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.
Alternatively, you could install an override of the core color helper by copying
In both of the above cases, you will also need to load the applicable assets. Here you have 3 choices:
To load the color picker assets for all pages, in config/site.php.
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);
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().
You can also load assets individually, using code based on that within the addHeaders() method.
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.
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.
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.