| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
|---|
| 2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 3 | <html> |
|---|
| 4 | <head><title>Farbtastic: jQuery color picker plug-in</title></head> |
|---|
| 5 | <body> |
|---|
| 6 | <h1 class="title">Farbtastic: jQuery color picker plug-in</h1> |
|---|
| 7 | <div class="content"><p>Farbtastic is a <a href="http://www.jquery.com/">jQuery</a> plug-in that can add one or more color picker widgets into a page. Each widget is then linked to an existing element (e.g. a text field) and will update the element's value when a color is selected.</p> |
|---|
| 8 | |
|---|
| 9 | <p>Farbtastic uses layered transparent PNGs to render a saturation/luminance gradient inside of a hue circle. No Flash or pixel-sized divs are used.</p> |
|---|
| 10 | |
|---|
| 11 | <p>Farbtastic was written by <a href="http://www.acko.net/dev/farbtastic">Steven Wittens</a> and is licensed under the GPL.</p> |
|---|
| 12 | |
|---|
| 13 | <h2>Basic Usage</h2> |
|---|
| 14 | <ol> |
|---|
| 15 | <li>Include farbtastic.js and farbtastic.css in your HTML:<br /> |
|---|
| 16 | <div class="codeblock"><code><script type="text/javascript" src="farbtastic.js"></script><br /><link rel="stylesheet" href="farbtastic.css" type="text/css" /></code></div> |
|---|
| 17 | </li> |
|---|
| 18 | <li>Add a placeholder div and a text field to your HTML, and give each an ID:<br /> |
|---|
| 19 | <div class="codeblock"><code><form><input type="text" id="color" name="color" value="#123456" /></form><br /><div id="colorpicker"></div></code></div> |
|---|
| 20 | </li> |
|---|
| 21 | <li>Add a ready() handler to the document which initializes the color picker and link it to the text field with the following syntax:<br /> |
|---|
| 22 | <div class="codeblock"><code><script type="text/javascript"><br /> $(document).ready(function() {<br /> $('#colorpicker').farbtastic('#color');<br /> });<br /></script></code></div> |
|---|
| 23 | </li> |
|---|
| 24 | </ol> |
|---|
| 25 | <p>See demo1.html and demo2.html for an example (jquery.js is not included!).</p> |
|---|
| 26 | <h2>Styling</h2> |
|---|
| 27 | <p>The color picker is a block-level element and is 195x195 pixels large. You can control the position by styling your placeholder (e.g. floating it).</p> |
|---|
| 28 | <p>Note that the black/white gradients inside wheel.png and mask.png were generated programmatically and cannot be recreated easily in an image editing program.</p> |
|---|
| 29 | <h2>Advanced Usage</h2> |
|---|
| 30 | <h3>jQuery Method</h3> |
|---|
| 31 | <dl> |
|---|
| 32 | <dt>$(...).farbtastic()<br /> |
|---|
| 33 | $(...).farbtastic(callback)</dt> |
|---|
| 34 | <dd>This creates color pickers in the selected objects. <code>callback</code> is optional and can be a:</p> |
|---|
| 35 | <ul> |
|---|
| 36 | <li><em>DOM Node</em>, <em>jQuery object</em> or <em>jQuery selector</em>: the color picker will be linked to the selected element(s) by syncing the value (for form elements) and color (all elements).</li> |
|---|
| 37 | <li><em>Function</em>: this function will be called whenever the user chooses a different color.</dd> |
|---|
| 38 | </dl> |
|---|
| 39 | <h3>Object</h3> |
|---|
| 40 | <dl> |
|---|
| 41 | <dt>$.farbtastic(placeholder)<br /> |
|---|
| 42 | $.farbtastic(placeholder, callback)<br /> |
|---|
| 43 | </dt> |
|---|
| 44 | <dd>Invoking <code>$.farbtastic(placeholder)</code> is the same as using <code>$(placeholder).farbtastic()</code> except that the Farbtastic object is returned instead of the jQuery object. This allows you to use the Farbtastic methods and properties below.</p> |
|---|
| 45 | <p>Note that there is only one Farbtastic object per placeholder. If you call <code>$.farbtastic(placeholder)</code> twice <em>with the same placeholder</em>, you will get the same object back each time.</p> |
|---|
| 46 | <p>The optional <code>callback</code> argument behaves exactly as for the jQuery method.<br /> |
|---|
| 47 | </dd> |
|---|
| 48 | </dl> |
|---|
| 49 | </dd> |
|---|
| 50 | </dl> |
|---|
| 51 | <h3>Methods</h3> |
|---|
| 52 | <dl> |
|---|
| 53 | <dt>.linkTo(callback)</dt> |
|---|
| 54 | <dd>Allows you to set a new callback. Any existing callbacks are removed. See above for the meaning of <code>callback</code>.</dd> |
|---|
| 55 | <dt>.setColor(string)</dt> |
|---|
| 56 | <dd>Sets the picker color to the given color in hex representation.</dd> |
|---|
| 57 | <dt>.setColor([h, s, l])</dt> |
|---|
| 58 | <dd>Sets the picker color to the given color in normalized HSL (0..1 scale).</dd> |
|---|
| 59 | </dl> |
|---|
| 60 | <h3>Properties</h3> |
|---|
| 61 | <dl> |
|---|
| 62 | <dt>.linked</dt> |
|---|
| 63 | <dd>The elements (jQuery object) or callback function this picker is linked to.</dd> |
|---|
| 64 | <dt>.color</dt> |
|---|
| 65 | <dd>Current color in hex representation.</dd> |
|---|
| 66 | <dt>.hsl</dt> |
|---|
| 67 | <dd>Current color in normalized HSL.</dd> |
|---|
| 68 | </dl> |
|---|
| 69 | </div> |
|---|
| 70 | </body> |
|---|
| 71 | </html> |
|---|
