UvumiTools ColorSphere Plugin

We can't take all the credit for this one. It is heavily inspired by Color Jack's color sphere, but rewritten, improved, optimized and simplified for the Mootools Javascript Framework.

We needed a color picker with the following features :

• As simple as possible so that casual users can easily choose a color, without spending too much time understanding how it works.
• Ability to easily include several color picker objects on a single page without using too much resources.
• Allows color values to be easily submitted with other form values.
• The color modification has to be updated in real time in the document, so we needed some visual feedback functionality.

• Simple: Lets you select a color in one click. Some pickers offer inputs for RGB, HSB, CMYK and hexadecimal, while most users have no idea what they stand for. With UvumiTools ColorSphere, it is limited to the hexadecimal value, the web standard, so advanced users can still type colors in.
• Easy to implement: For the basic mode, you only need to understand basic CSS selectors. If you're more familiar with javascript, you can make it interact with the rest of your page using the callback functions.
• Optimized memory usage: Need 10 color pickers or more in a single page? No problem. If set up properly, one instance of the picker can handle as many inputs as you want. If you pass a collection of inputs on initialization, it will not create an individual picker for each input. Instead, the same picker will be moved and updated from one input to another. And it will always remember the previous value of each input. As a result, the pages will load faster, and browser memory usage will not be overly consumed.
• Non-obtrusive: Plugs into a regular text input. This means you just have to build a regular HTML form in which you can type the color as a hexadecimal value. Then, you apply the ColorSphere javascript plugin, and the input is replaced with a 'pick' button (stylizable with CSS) which will display the color sphere. The form can still be submitted, and the server will receive the updated hex value with the same input name.
• Retains manual input override: If you know the exact hexadecimal value you're looking for and cannot nail it with the picker, no problem, the hexadecimal indicator on top of the picker also works backward : you can type a value here and if it's valid, the sphere will set itself to the matching color.
• Accepts default input: You can set a default color for each input by simply defining a hexadecimal value when you output the HTML code. If defined, the picker will use this value as a default color and adjust the cursor accordingly. This is particularly useful when you are editing a previously saved color scheme.
• Callback Functions: The class has two event callback functions, onChange and onComplete. Those functions are fired respectively when the picker is beeing dragged, and when it is released. They receive the current color hexadecimal value and the active input as parameters. You can use this information to intereact with your document, like in the example above. You can even use the onComplete function to send an ajax request, if you don't want to bother submiting a form manually.
• Cross-Browser: Was tested in the major browsers: Firefox 2 & 3, Internet Explorer 6 & 7, Opera 9, Safari 3 and Chrome. All on Windows systems. We didn't get a chance to test on Mac or Linux. If anyone encounters any problems in other browser/operating systems, please let us know. We only support real browsers; No need to email us because it doesn't work in IE4 or AOL. We know that, and it's fine with us.
• Customizable: The default sphere is black and 128 pixels big, but this is easily changed. The style is set in a separate CSS file that you can modify to match you site's design. Also included is the source PSD file for Adobe Photoshop, which allows you to create a sphere with different background color or size.
• Draggable: You can drag the sphere if it's blocking another input. Just move the mouse to the top of the sphere container, where the cursor should turn into a multiple direction arrow. Just hold the mouse button drown in this area to drag the sphere somewhere else.

What you'll need:

• A website where you can include javascripts: Sounds obvious, but some platforms don't allow users to include <script> tags. If you are your own webmaster, you're set.
• Mootools 1.2: To use this plugin you'll need Mootools 1.2, but if you are already using another javascript framework like Prototype or JQuery, you may have to decide which one you want to keep because those frameworks were not designed to work together, and they ofen conflict with each other.
  And yes, you actually do need version 1.2 of Mootools. If you are already using a previous version of Mootools then the gallery will not work unless you upgrade. Sure, upgrading is a slight hassle, but trust us, it's worth it in the long run.

• Mootools Dependencies: If your website already contains some Mootools 1.2 stuff (from this wesite or elsewhere), then you're stoked because you can use a single Mootools library for everything. All you'll need is the UvumiTools Dock Menu script, and to make sure your library contains the following classes:

  • Core
    • Core
    • Browser
  • Native
    • Array
    • Function
    • Number
    • String
    • Hash
    • Event
  • Class
    • Class
    • Class.Extra
  • Element
    • Element
    • Element.Event
    • Element.Style
    • Element.Dimensions
  • Utilities
    • Selectors
    • DomReady
  • Plugins
    • Drag
    • Drag.Move
    • Color
    • Assets

Initialization

Arguments

• Selector: string defining a CSS rule that will select the elements to be turned into color pickers. These elements should be text inputs in the beginning.
• Options: an object that will allow you to modify some properties of the picker. As the name suggests, options are optional.
  

Options

• defaultColor: If an input has no color value on initialization, the cursor should still have a default position. The default one is #ffffff (white), but you can set it to a different value, by passing an hexadecimal string here.
• specterImage: If you customize the sphere with a new background image, or rename/move it, the script needs to know because it tries to preload it on intialization. This is not required for the script, this is only for a better looking result and if you want to update this value, you must specify a path, absolute or relative to the document (not to the javascript file). The default value is css/circle.jpg because that's where the file is assumed to be when you download the package.
• cursorImage: Like the specterImage, the script tries to preload the images required by the CSS so they show up instantly the first time you display the sphere. This option is for the circular cursor. The default is css/miniCurr.gif. So you must have an image file at this location, or set this option.
• buttonText: The source inputs are replaced by <button> elements. This indicates what should be written in the button. The default is "Pick", but you can write whatever you want, including an image tag (yes, it is valid). Don't forget you can also style those buttons in the provided CSS file.
• onChange: This option recieves a function. The function will be executed everytime the sphere's cursor is moved. You can use this function to do anything javascript will allow, including modifying the color of an HTML element, because it receives the the new color value and the source input as arguments. See the last example to see how this option works.
• onComplete: Same is onChange, except it is only fired when the cursor is released. It is useful to have two separate functions, because onChange will be fired much more often than onComplete (every time the cursor is color cursor moves actually). This way you can set the simple tasks to onChange (like updating an element's color), and do the big stuff when the color has been picked in the onComplete function (like submitting the new color value to the server).

Implementation

First, you simply import the files provided in the zip archive into your document. While you can insert <script> tags anywhere, we recommend you put them inside the <head> tag of your document:

Then you must prepare the HTML code for your ColorSphere. For one color, all it requires is a single text input. Let's say we want the color to be set to pure red the first time you open the picker. So we set the input value to "#f00". We suppose the reason you pick a color is to submit it to a server, so we put this input inside a form.

So far we have a form that will send a value named 'color' as a 'POST' parameter to the script 'submit-color.php', which is a name we just made up. It will be your job to write a server-side script to catch this value and do something useful with it. The value for 'color' is '#F00' unless the user types in something else. Techinically it is functional and could totaly work as it is.

Then we are ready to initialize the sphere script. By default, the sphere recieves only one argument, the selector. The selector is a string that works like a CSS rule. Using the exact same syntax, it will tell the script which HTML elements it should apply to. In our case there is only one input, so we are going to use a '#' for id selection, but you can create more complex rules, using tags and class selections. If you are familiar with CSS styling, this should not be a problem for you.

In the end, we put everything together. Mootools requires a strict Doctype to work properly. We get something like this:

Technically speaking, that should work. The text input will be virtually replaced with a 'pick' button. Virtally, because the input still exists, it is simply hidden. It will be constantly updated, and submited along with the form.

This is for the default, simple usage. We are going to see how to apply the sphere to several inputs. Let's say we have four color inputs this time, all needing the ColorSphere.
We saw how to use an ID selector. We could use an ID selector again, by just listing the inputs IDs, separated by commas: #input1,#inpu2,#input3,#input4. It will work, but we can use any CSS rule (including advanced CSS3 rules that are not even supported by all browsers).
We could use a rule to apply the sphere to any input inside the form: form#color-form input . Problem is, this will turn every input tag into color pickers, even if they are checkboxes or radio buttons. Probably not what we want.
The best way to filter the inputs we want is to use the class property: we add a class to the inputs we want to apply the sphere to, and we use this class in the selector, thanks to the dot character:

If we have two forms, and we went a separate picker for each, we can create two instances (eventually with different options), and specify in the css rules which form they should affect:

• No gray level: Yeah, if you take a closer look at the ColorSphere, you'll notice that beside pure black and pure white, there are no gray values. The only way to select one is to type it in. Not much can be done about it, except adding an extra column on the side with a gray gradient. But the point of this color picker is to be as simple as possible, so we're leaving it as is for now.
• One color at a time: Because the ColorSphere is optimized so one instance covers every color input, it also means only one picker can be displayed at atime. As a result, if you want to adjust two colors simultaneously, you'll have to open/close the picker on every adjustment, which might become annoying. You can still create multiple instances of the picker, assigning there is a different collection of inputs for each instance, but in this case your resources will not be optimized how we intended.

• 20080922 - Version 1.0.0 : Initial release. Stable with Mootools 1.2