You may add your own palettes to this folder ( color_palettes/ ), and they will be recognized and utilized by SoftMoon WebWare’s JavaScript and PHP code base, as long as they follow the formatting rules below:

Note the basic Json structure in the existing palette files, and copy it, with the following cautions and possibilities:

.txt files (or similar) should be in “loose” Json format, that is, they may contain whitespace. All property identifiers including numerical identifiers and any of their values that are strings, must be quoted with "strait" double quotes (no single quotes or “curly” quotes). If the quoted identifiers or values must contain a strait double-quote, then it must be escaped with a \ character like this:

"property": "my \"value\" of this property"

If you need to use the \ character, it must be escaped using itself like this:

"property": "the path to my file is: C:myFolder\\myFile.php"

You may not escape any other characters with the \ character.

Palette names may be almost anything except_user_palettes” capitalized exactly this way. “_User_Palettes,” “_User_palettes,” and “_user_Palettes,” for example, would be acceptable.

Palette names may not contain either character : (

but color names may contain any including those characters.

Color names may be anything exceptgetColor” capitalized exactly this way. “GetColor,” “getcolor,” and “Getcolor,” for example, would be acceptable.

Color names that are either •prefixed with whitespace or •enclosed within the characters found in the Array in the property SoftMoon.WebWare.buildPaletteTable.refColorHTML are valid names of reference, but when displayed by the “buildPaletteTable” function, it is the color’s definition listed, not the color’s name. These enclosing characters are by default « »

Similarly, color definitions that are either •prefixed with whitespace or •enclosed within the characters found in the Array in the property SoftMoon.WebWare.buildPaletteTable.refColorHTML are added into the table structure created by the “buildPaletteTable” function, but instead of replacing the color name, the definition text is placed within a <div></div> inside the color swatch <td></td> (the first column).

The colors may be defined any way that SoftMoon WebWare’s rgb() function can interpret (see the comments and documentation of that file) which may be a string or an array of decimal RGB values. This allows you to create palettes with a format that is most usable for your other custom code projects. This includes defining colors as other colors:

{"myPalette": {"palette": {

"My Favorite Color": "blue",

"My Favorite Specific Color": "X11: Turquoise1",

"My Favorite Alias Color": "myPalette: My Favorite Specific Color"

} } }

Note in the first color of the example above, “blue” is looked for in the “default palette”, which is initially (by default) the “HTML” palette. (The default palette name in JavaScript is found in the following property: SoftMoon.defaultPalette )

You may chain color definitions (defining colors as other colors) multiple times from one color to the next, through the same palette or multiple palettes, but it must end at some point with a non-palette color-model recognized by the rgb() function (hex, RGB, CMYK, etc...)

The palette name(s) should be property(ies) at the top level of the defined Json object. (You may define more than one palette per file.) The value(s) of these property(ies) should be objects with the following recognized properties:

palette: {}

requireSubindex: ("true" || "false")

header: ("headerText" || ["headerText1","headerText2",])

footer: ("footerText" || ["footerText1","footerText2",])

getColor: function() {}

buildPaletteHTML: function() {}

The “palette” value is the data object for the palette and will be copied into the Palette Object created internally. This “palette” property is the only required property of the palette definition. Each data member, each a property of the “palette” data object, has a property name corresponding to either the color name, or the name of another sub-palette. Sub-palettes may contain more colors or sub-palettes.

The “requireSubindex” property controls whether or not the names of sub-palettes are required to find the proper color. If all the colors on a palette and the sub-palettes therein have different names, the names of the sub palettes are irrelevant, and may be ignored (as in the Crayola palette). If colors in different sub-palettes have the same name (as in the Brewer palette) the sub-palette name is required. If the “requireSubindex” property is “true” then the standard getColor() method requires sub-indexing color names, and the generated event handlers on the HTML table return full sub-palette indexing; and logically the opposite is true for “false”. By default, if no value is passed for “requireSubindex”, the sub-palette name(s) is(are) not required by getColor() to be indexed (conflicting sub-indexes will produce the value from the first one created), but the HTML table’s event handlers will return fully indexed color names.

(You may want to modify the Crayola palette file and remove the line setting “requireSubindex” to “false”. As noted, this will cause clicking on the colors to include sub-index info, but if you type in a Crayola color without the sub-index, it will still be recognized.)

Headers and footers may be a single string of HTML or an array of these strings. These will each get their own row within a <thead> or <tfoot> section of the JavaScript-generated HTML table.

If you want to create a palette with data that is arranged in a different way, you may define your own JavaScript “getColor” function through the .getColor() property of the palette, and also your own “buildPaletteHTML” function. The former should return a color value that is interpretable by SoftMoon WebWare’s JavaScript rgb() function, while the latter should return a DOM element that can be inserted into the document. This DOM element should be complete with event handlers ready to go. The DOM element passed back should have a non-standard (user-defined) method named .set$styles() which is called after the element is inserted into the document; it can set the inline style attributes to color palette swatches, or whatever (inline styles will not take effect unless the DOM element is part of the document).

Since PHP may not accept a Json file including embedded JavaScript functions as valid Json, you have two options:

(1) PHP need not worry about that palette, so its filename should end with .js and PHP will ignore it. Only the JavaScript rgb() function will utilize it.

(2) You want PHP to utilize it, so it must be encapsulated in a PHP file (with a .php filename extension). This file when called should echo the Json format, unless needed by PHP and called with the $_GET['noEcho']==TRUE parameter set like this: color_palettes/myNonstandardPalette.json_palette.php?noEcho=true

When needed by PHP and called this way, your custom palette file should add to the existing array of SoftMoon WebWare’s palettes the new palette and its data as an implementation of the PHP “Palette Class” Object which contains the proper “getColor” method.

You may therefore utilize the Palette Object code-structure as a color-modeler. Your palette data need be only an empty object, and the suppled “getColor” function may accept the color passed in as data to be manipulated or otherwise processed, and pass back the proper rgb array (or any format recognized by the rgb() functions). Do note, though, that the SoftMoon.WebWare.rgb.from. object is specifically for color-space-modelers; your cuctom code is best to define additional color-modelers there (remember to always name them in lowercase if so), but it may be more dynamic and flexible to utilize the palette-oriented structure.