ColorMatrix

Generates a simple but flexible color matrix

Examples

Without any Javascript involved:

Include the javascript file and add the next HTML code according to the desired case:

1) To create an input which on click shows the color matrix and place the #HEX color value in it:

<input type='color'>
1a) If you want to return the INT_VALUE instead the #HEX value add the class "intcolor":

<input type='color' class="intcolor">
2) To create a small (10x10px) pickcolor box (can be any HTML element) which on click it shows the color matrix and set its background color (then you could read that value with Javascript):

<div class='colormatrix'>
3) To create a small pickcolor box and which on click stores the Int value (see INT_VALUE) in the input hidden.

<input type='hidden' class='colormatrix'>
3a) If you want to return the #HEX value instead the INT_VALUE value add the class "hexcolor":

<input type='hidden' class="colormatrix hexcolor">

Click an HTML element and colorize it:

<span>This is a text</span>

//On click will launch the color matrix and then will change the background color.
$("span").setMatrix();

Click an HTML element and change a style color:

<h1>This is a title</h1>

//On click will launch the color matrix and then will change the text color.
$("h1").setMatrix({style: "color"});

//On click will launch the color matrix and then will change the outline color.
$("h1").setMatrix({style: "outlineColor"});

Note: Default value is: backgroundColor.

Use a trigger (button or any element) to launch the color matrix on click and change other's element background color:

<button>Pick Color</button>
<div>Some text</div>

//On click, will change "div" background color (can be any selector)
$("button").setMatrix("div");

Several triggers/targets can be used like:

//On click, will change any "div","h1" or "h2" background color (can be any selector)
$("button").setMatrix("div,h1,h2");

//On click (on any button or div with class button), will change "#id" background color
$("button,div.button").setMatrix("#id");

//On click (on any button or div with class button), will change any "div","h1" or "h2" 
//background color
$("button,div.button").setMatrix("div,h1,h2");

The targets can be:

selector: e.g. "div > p"
jQuery object: e.g. $("<div>")
Array of objects: e.g. [ $("div"),$("h2") ]
function: e.g. function(rgbcolor, intcolor) { ... }

Note: to convert rgbcolor to #HEX, use:

var hexcolor = jQuery.colorMatrix.prototype.toHex(rgbcolor);

Change a target and a style:

<button>Pick Color</button>
<div class='target'>Some text</div>

//Will show the color matrix on button click and change ".target" text color
$("button").setMatrix({target : ".target", style: "color"});

Launch the color matrix on event (different than click):

<button>Pick Color</button>
<div class='target'>Some text</div>

$("button").dblclick(function() {
      //Will show the color matrix and change ".target" background color
      $(this).showMatrix(".target");
});

Note: the options for showMatrix() and setMatrix() are exactly the same.

INT_VALUE

All colors are numbered from 0 to n. So, in a 16x16 matrix, colors ids will be assigned from 0 to 255.

You can store that value in your DB instead of storing the HEX/RGB/HSL value (or its 65k Int conversion), which will be more space efficient.

Note: for a number of colors higher than 256 it may be better to just convert its color Int value (65k) as there is no space gain.

To display the color again, its INT_VALUE can be converted using the same code that was used to generate it:
var realcolor = jQuery.colorMatrix.prototype.Calc(INT_VALUE);
If you set any advanced options for "cols","rows","gray" and "transp" (see ADVANCED OPTIONS), they are required to be specified with the same values which were used to generate the int.

For example:

var cols = 16, rows = 16, gray = 'auto', transp = true;
var realcolor = jQuery.colorMatrix.prototype.Calc(INT_VALUE, cols, rows, gray, transp);

If you want to convert the colors at the Server side, you can use the PHP function (@link) to generate them.

ADVANCED OPTIONS

.setMatrix() and .showMatrix() accept the following options (Default values are shown. Click on the option name to jump to its definition):

 {
        id      : 'colormatrix',        //string    : id for the color matrix
        rows    : 10,                   //int       : number of rows of colors to show. In general terms is the LUMINOSITY steps.
        cols    : 12,                   //int       : number of cols of colors to show. In general terms is the number of HUE steps.
        gray    : 'auto',               //int       : number of gray tones. When not set its equal to cols.
        transp  : false,                //bool      : Add transparent color to the matrix
        skin    : 'auto',               //string    : which design will be applied to the colormatrix box
        width   : 'auto',               //int       : This value usually will be set in CSS.
        position: 'right-middle',       //string    : e.g., left-top, right-bottom, top-left, bottom-center, center-middle
        show    : true,                 //bool      : When false, it will not show up during showMatrix(). (@see "show")
        single  : false,                //bool      : true means "fixed", false means "flexible". (IMPORTANT: @see "single")
        inline  : false,                //bool      : Set the color matrix to a static position
        style   : 'backgroundColor',    //string|null : style to change by default. e.g. borderColor, color, etc... When null, it would not change target style
        colors  : []                    //array     : Colors can be passed as an array as well.
 }

"id"

Different color matrices can be set if different id is used.
There is no need to use a different ID if you are using different targets, for example:

$("button.one").setMatrix("div.target_one");
$("button.two").setMatrix("div.target_two");

In the previous example, the same color matrix will be used for both buttons and targets.
Use a different Id if you need different values for any option listed above, for example:

$("button.one").setMatrix({id: "cm_one", target:"div.target_one", transp: true});
$("button.two").setMatrix({id: "cm_two", target:"div.target_two", position: "top-right"});

"rows" | "cols" | "gray" | "transp"

You can customize the number of colors to show. For example, a matrix of 10 cols x 5 rows will show (obviously) 50 colors.

If you don't set the "gray" option, (in the previous example) it will show 40 colors and 10 grayscale colors, as it uses the
number of columns by default (and displayed as last row).

You can change that behavior, setting the "gray" option:

gray = 1, will produce white only.
gray = 2, will produce white/black.
gray = 3, will produce white/gray/black.
gray = 4, will produce white/light gray/dark gray/black
and so on...

If you set the "transp" value to "true" (boolean), it will add an extra "transparent" color to the matrix (after the gray block).

"skin"

In the file colormatrix.css, 6 different "matrix" skins are included.
These were designed to fit different matrices sizes (when skin : 'auto' is used).
You can also set manually any class by using the "skin" option.

These are the skins:


    css class   auto                         col. width     Recommended (colors)
    --------    ------                       ----------     -------     ------
    small       less or equal to 64 colors      10px        8 x 8       64
    comfort     from 65 to 128 colors           14px        12 x 10     120
    grid        from 128 to 197 colors          10px        16 x 8      128
    smooth      from 198 to 512 colors          7px         16 x 16     256
    compact     from 512 colors to 2500         4px         30 x 30     900
    pixel       larger than 2501 colors         1px         100 x 100   10k

Note: using more than 1000 colors will result in a loss of performance (try to use "show" and "single" options to increase performance)

"width" (int value, dont set "px")

When "auto" is specified, it will calculate it according to the selected skin.
You may need to change this value if, for example, you want to use your own skin or
to align colors generated by other algorithm (see "colors").

When using predefined skins, you can refer to the "col. width" size to adjust the width manually.
For example, to produce a 4 column (and 4 rows) matrix out of a 16x1 configuration, and using the "comfort" skin,
the width should be "cols" * 14px, which is : 56, and to produce a 4 columns in "small" skin (default for
that amount of colors), the width should be 40; and for 8 columns, width would be 80.

"position"

Sets the "floating" color matrix position in relation to the trigger (for example : button, input box).
The available positions are:

left-top
left-middle
left-bottom
right-top
right-middle
right-bottom
top-left
top-center
top-right
bottom-left
bottom-center
bottom-right
center-middle

Note: left-top and top-left (for example) are not the same. In the case of left-top, it will be placed in the left side of the trigger and then aligned to the top border. While top-left, will be placed in the top side of the trigger and then aligned to the left side border.

"show"

Pre-loading a matrix will increase the loading time, but will improve response (during trigger event), as by default
the matrix is created during the event. Specially when a matrix contains more than 1000 colors, the response time
can be significant.

If you want to create the matrix on load (instead of on event), set this option to "false" when calling showMatrix()
(it wont work calling for setMatrix() first as it will not be executed on load).

One way to set it:

$("button").showMatrix({show: false}).setMatrix();
Or with custom options:

$("button").showMatrix({
    id: "mycolor",
    target: "#myid", 
    show: false, 
    cols: 50, 
    rows: 50
}).setMatrix({id: "mycolor"});

NOTE: When calling .setMatrix in the above examples, additional options are not required. Only "id" is required when it is explicitly defined in showMatrix().

Other way to set it is:

$("button").showMatrix({
    id: "mycolor",
    target: "#myid",
    show: false,
    cols: 50, 
    rows: 50
}).click(function() {
    $("#mycolor").toggle();
});

"single"

This option will exchange flexibility for performance.
As explained before (see example(4)), you can reuse the matrix with different triggers and targets like:

//flexible example:
$("button.many").setMatrix("div");
$("button.other").setMatrix("h1,h2");

In which the same id (#colormatrix by default), is reused, and every time, position (in relation to trigger) and events (related to targets) need to be regenerated as well (only the matrix apparience is kept).

While in small matrices that means nothing, in a matrix with many colors (for example more than 1000 colors) means slowing the browser.

If you are sure that a color matrix will be launched with only one trigger (e.g. button) and that it targets to a fixed number of elements (it can be one or more but it should not change), then you can safely set this option to "true" to gain its benefits.

If you want to use this option, but you need to use more than one trigger or you need to change your targets, you can set different ids for each matrix (and still get the benefits), like:

//fixed example:
$("#unique").setMatrix({id: "matrix_1",target:"div", single:true, cols: 50, rows: 50});
$("#onlyone").setMatrix({id: "matrix_2",target:"h1,h2", single:true, cols: 100, rows: 100);

These "fixed" examples will be a lot more faster than the "flexible" ones (without "single: true").

"inline"

Setting "inline" to "true", will set the color matrix to a static position (inline) instead of floating

To set it "inline" you will need to add its own id:

$("span.here").showMatrix({id: "static", inline: true, target: "#myid"});
NOTE: setting "position" may be useless in this case.

"colors"

An array of colors (HTML colors as string) to use instead the generated one. This is useful if you want to limit your users to use specific colors (be sure to match the number of colors in the array with the values cols x rows).
You can use your own color generation algorithms to create different color matrices.

Examples:

$("#mycolors").setMatrix({
    colors: ["red","blue","green","orange","yellow","pink","brown","purple","white","gray","black"]
});

$("#mycolors").setMatrix({
    colors: ["#F33","#FF6699","rgb(10,10,150)","rgba(255,100,100,0.5)","hsl(120,100%,50%)"]
});

Note: use "transparent" to specify the transparent color. You have to specify "transp : true" to enable it.