Файл: documentation/index.html
Строк: 661
<?php
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>jColor Documentation</title>
<link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Source+Code+Pro|Open+Sans:400,700">
<link rel="stylesheet" type="text/css" href="../jcolor.css">
<link rel="stylesheet" type="text/css" href="assets/documentation.css">
<link rel="stylesheet" type="text/css" href="assets/github.min.css">
<script type="text/javascript" src="assets/jquery.js"></script>
<script type="text/javascript" src="assets/highlight.min.js"></script>
<script type="text/javascript" src="assets/javascript.min.js"></script>
<script type="text/javascript" src="assets/css.min.js"></script>
<script type="text/javascript" src="assets/xml.min.js"></script>
<script type="text/javascript" src="../jcolor.js"></script>
</head>
<body class="cp">
<script type="text/javascript" src="assets/documentation.js"></script>
<h1 class="page-title">
<img class="logo" src="assets/logo.png"> <span class="desc">- a jQuery color picker</span>
</h1>
<article class="intro">
<h1>Introduction</h1>
<section>
<p>
Thank you for purchasing jColor color picker for jQuery! This page contains a brief introduction to the color picker, followed by a number of use case examples. If you are looking for a more complete technical specification of jColor's capabilites and API, please refer to the README.txt file.
</p>
<p>
First off, <em>a little</em> theory. This color picker lets the user select a color, through the either <a href="http://en.wikipedia.org/wiki/HSL_and_HSV">HSL</a> or the <a href="http://en.wikipedia.org/wiki/RGB_color_model">RGB</a> color space. In short, the HSL (hue, saturation, lightness) is a color model constructed to be as intuitive as possible for humans, while the RGB (red, green, blue) color model is the classical way that computers use to represent color. Personally, I recommend using the HSL color space, if there is no special reason to use RGB.
</p>
<p>
jColor works, like most other jQuery plugins, by attaching itself to an element selected using jQuery's selector function, as illustrated in all examples below. Once attached, jColor transforms the selected element to an expandable daub, showing the currently selected color. By clicking and thus expanding the daub, the user is exposed to a set of sliders that correspond to either the HSL or RGB color components.
</p>
<p>
The currently selected color can be accessed in a number of different ways and there is always an option to transform the color from RGB to HSL and vice versa. How to access the current color is shown in the later examples.
</p>
<p>
Lastly, if you have any questions that are beyond the scope of this help file, please feel free to message me via my user page contact form <a href="http://codecanyon.net/user/ogustafsson" target="_blank">here</a>.
</p>
</section>
</article>
<article class="toc">
<h1>Table of Contents</h1>
<ul>
<li><a href="#basic">Basic usage</a></li>
<li><a href="#configure-colors">Configuration: Specifying color space and initial color</a></li>
<li><a href="#configure-presentation">Configuration: Presentation</a></li>
<li><a href="#configure-static">Configuration: Static slider backgrounds</a></li>
<li><a href="#configure-custom-events">Configuration: Custom expand/collapse events</a></li>
<li><a href="#configure-bounds">Configuration: Custom viewport</a></li>
<li><a href="#configure-modal">Configuration: Modal mode</a></li>
<li><a href="#getting-color">Getting the selected color</a></li>
<li><a href="#listening">Listening for color changes</a></li>
<li><a href="#theming">Theming and styling</a></li>
<li><a href="#cleanup">Cleanup</a></li>
</ul>
</article>
<article id="basic">
<h1>Basic usage</h1>
<section>
The color picker automatically picks up the CSS color of the element it is attached to, if no color is given as a configuration parameter.
</section>
<section>
<pre>
<code class="xml">
<div class="my-color-picker" style="color: green"></div>
</code>
</pre>
<pre>
<code class="javascript">
$('.my-color-picker').colorpicker();
</code>
</pre>
<h2>
Live demo
<a href="examples/basic.html" target="_blank">Show standalone</a>
<a href="examples/basic.html" class="full-source">View full source</a>
</h2>
<iframe src="examples/basic.html" frameborder="0" class="live-example"></iframe>
</section>
</article>
<article id="configure-colors">
<h1>Configuration: Specifying color space and initial color</h1>
<section>
<p>The default color space is HSLA (hue, saturation, lightness, alpha), but can be overridden by passing along the <code>colorSpace</code> option. Valid values are <code>'hsla'</code>, <code>'hsl'</code>, <code>'rgba'</code> and <code>'rgb'</code>.</p>
<p>The initial <code>color</code> option can be either a hexadecimal string, a CSS color string (e.g. <code>'rgb(0, 255, 0)'</code>), or an object containing the color component values.</p>
</section>
<section>
<pre>
<code class="xml">
<div class="color-picker-rgba"></div>
<div class="color-picker-hsl"></div>
<div class="color-picker-hsla-css"></div>
</code>
</pre>
<pre>
<code class="javascript">
$('.color-picker-rgba').colorpicker({
color: { r: 0.95, g: 0.75, b: 0.2, a: 0.9 },
colorSpace: 'rgba'
});
$('.color-picker-hsl').colorpicker({
color: '#faaab5',
colorSpace: 'hsl'
});
$('.color-picker-hsla-css').colorpicker({
color: 'hsla(120, 50%, 40%, 0.8)',
});
</code>
</pre>
<h2>
Live demo
<a href="examples/configure-colors.html" target="_blank">Show standalone</a>
<a href="examples/configure-colors.html" class="full-source">View full source</a>
</h2>
<iframe src="examples/configure-colors.html" frameborder="0" class="live-example"></iframe>
</section>
</article>
<article id="configure-presentation">
<h1>Configuration: Presentation</h1>
<section>
<p>It possible to show color component labels by passing the <code>labels</code> key with the boolean value <code>true</code> when creating the color picker.</p>
<p>It is also possible to show a textual representation of the currently selected color in an expanded color picker. This behavior is controlled by the properties <code>displayColor</code> and <code>displayColorSpace</code>. The former may be a string with value <code>'hex'</code> or <code>'css'</code> and the latter may be any valid color space string, as specified in the previous section. If the <code>displayColorSpace</code> property is omitted, it will default to the color pickers color space.</p>
</section>
<section>
<pre>
<code class="xml">
<div class="color-picker-labels" style="color: hsla(42, 74%, 49%, 0.85)"></div>
<div class="color-picker-display-color" style="color: hsla(42, 74%, 49%, 0.85)"></div>
<div class="color-picker-labels-display-color" style="color: hsla(42, 74%, 49%, 0.85)"></div>
</code>
</pre>
<pre>
<code class="javascript">
$('.color-picker-labels').colorpicker({
labels: true
});
$('.color-picker-display-color').colorpicker({
colorSpace: 'rgb',
displayColor: 'hex',
});
$('.color-picker-labels-display-color').colorpicker({
labels: true,
displayColor: 'css',
displayColorSpace: 'hsla', // Redundant, this is the default
});
</code>
</pre>
<h2>
Live demo
<a href="examples/configure-presentation.html" target="_blank">Show standalone</a>
<a href="examples/configure-presentation.html" class="full-source">View full source</a>
</h2>
<iframe src="examples/configure-presentation.html" frameborder="0" class="live-example"></iframe>
</section>
</article>
<article id="configure-static">
<h1>Configuration: Static slider backgrounds</h1>
<section>
Some people prefer that the slider backgrounds does not dynamically update based on the current color. This option is available for both color spaces, but it is really only meaningful to use with RGB(A) sliders.
</section>
<section>
<pre>
<code class="xml">
<div class="color-picker-rgba-static"></div>
<div class="color-picker-hsla-static"></div>
</code>
</pre>
<pre>
<code class="javascript">
$('.color-picker-rgba-static').colorpicker({
color: '#f010f0a0',
colorSpace: 'rgba',
staticComponents: true
});
$('.color-picker-hsla-static').colorpicker({
color: '#008080a0',
colorSpace: 'hsla',
staticComponents: true
});
</code>
</pre>
<h2>
Live demo
<a href="examples/configure-static.html" target="_blank">Show standalone</a>
<a href="examples/configure-static.html" class="full-source">View full source</a>
</h2>
<iframe src="examples/configure-static.html" frameborder="0" class="live-example"></iframe>
</section>
</article>
<article id="configure-custom-events">
<h1>Configuration: Custom expand/collapse events</h1>
<section>
The expanding and collapsing of the color picker can be customized by providing jQuery event strings through the <code>expandEvent</code> and <code>collapseEvent</code> options. Note that it is possible to pass several events in the same string, all of which will trigger the expand/collapse!
</section>
<section>
<pre>
<code class="xml">
<div class="color-picker-custom-events"></div>
</code>
</pre>
<pre>
<code class="javascript">
$('.color-picker-custom-events').colorpicker({
color: 'hsla(10, 30%, 30%, 0.7)',
expandEvent: 'mouseenter',
collapseEvent: 'mouseleave mousewheel'
});
</code>
</pre>
<h2>
Live demo
<a href="examples/configure-custom-events.html" target="_blank">Show standalone</a>
<a href="examples/configure-custom-events.html" class="full-source">View full source</a>
</h2>
<iframe src="examples/configure-custom-events.html" frameborder="0" class="live-example"></iframe>
</section>
</article>
<article id="configure-bounds">
<h1>Configuration: Custom viewport</h1>
<section>
By default, jColor makes sure that it does not expand beyond the visible screen space. In some cases it can be useful to restrict the expansion even further, in which case a custom bounding element can be specified using the <code>boundingElement</code> option. Its value should be a jQuery wrapped element. When specified, jColor does its best to not expand beyond the bounds of that element.
</section>
<section>
<pre>
<code class="xml">
<div class="my-container">
<div class="color-picker"></div>
</div>
</code>
</pre>
<pre>
<code class="javascript">
$('.color-picker').colorpicker({
color: { r: 0.3, g: 0.75, b: 0.72, a: 0.5 },
boundingElement: $('.my-container'),
});
</code>
</pre>
<h2>
Live demo
<a href="examples/configure-bounds.html" target="_blank">Show standalone</a>
<a href="examples/configure-bounds.html" class="full-source">View full source</a>
</h2>
<iframe src="examples/configure-bounds.html" frameborder="0" class="live-example"></iframe>
</section>
</article>
<article id="configure-modal">
<h1>Configuration: Modal mode</h1>
<section>
You can opt to disable pointer events (e.g. clicks) on the rest of the page, while the color picker is expanded. This feature is enabled by passing a <code>modal</code> option with a truthy value. Note: This feature is supported by all browsers that support <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/pointer-events#Browser_compatibility" target="_blank">pointer events</a>.
</section>
<section>
<pre>
<code class="xml">
<div class="color-picker-modal"></div>
<button href="#" onclick="alert('Thank you, come again!')">Click me!</button>
</code>
</pre>
<pre>
<code class="javascript">
$('.color-picker-modal').colorpicker({
color: '#e0b0a0',
modal: true,
});
</code>
</pre>
<h2>
Live demo
<a href="examples/configure-modal.html" target="_blank">Show standalone</a>
<a href="examples/configure-modal.html" class="full-source">View full source</a>
</h2>
<iframe src="examples/configure-modal.html" frameborder="0" class="live-example"></iframe>
</section>
</article>
<article id="getting-color">
<h1>Getting the selected color</h1>
<section>
The currently selected color can be output in various formats using the <code>toString()</code>, <code>toCssString()</code> and <code>toObject()</code>, functions which all take an optional color space argument. All three functions are used in the example code below.
</section>
<section>
<section>
<pre>
<code class="xml">
<div class="color-picker"></div><br><br>
<button class="get-color-btn">Get current color!</button>
<div class="outputs" style="margin-top: 1em;">
<div class="newcolor-hlsa-css"><b>CSS HSLA:</b> <span></span></div>
<div class="newcolor-rgb-hex"><b>Hexadecimal RGB:</b> <span></span></div>
<div class="newcolor-rgba-object"><b>Object RGBA:</b> <span></span></div>
</div>
</code>
</pre>
<pre>
<code class="javascript">
var myColorpicker = $('.color-picker').colorpicker({
color: 'hsla(192, 78.89%, 40.56%, 0.73)',
});
$('.get-color-btn').on('click', function () {
// Get the current color from the color picker and update things.
// We can use an existing reference to the jColor instance...
$('.newcolor-hlsa-css span').html(myColorpicker.toCssString());
// ... or get a new reference by calling the .colorpicker() function on the right element
$('.newcolor-rgb-hex span').html($('.color-picker').colorpicker().toString('rgb'));
$('.newcolor-rgba-object span').html(
prettyPrint($('.color-picker').colorpicker().toObject('rgba')));
// Set page background color to the colorpicker's color
$('body').css('background', myColorpicker.toCssString());
});
</code>
</pre>
<h2>
Live demo
<a href="examples/getting-color.html" target="_blank">Show standalone</a>
<a href="examples/getting-color.html" class="full-source">View full source</a>
</h2>
<iframe src="examples/getting-color.html" frameborder="0" class="live-example"></iframe>
</section>
</article>
<article id="listening">
<h1>Listening for color changes</h1>
<section>
<p>
Whenever the user picks a new color, a <code>newcolor</code> jQuery event is triggered. By listening to that event, we can keep other parts of our page in sync with the selected color.
</p>
<p>
The callback of a <code>newcolor</code> event gets passed four arguments; the jQuery event, the jColor color picker instance, a single letter string specifying which color component that was last changed, and finally a number normalized to the range [0,1] representing the color component's new value.
</p>
</section>
<section>
<section>
<pre>
<code class="xml">
<div class="color-picker-1"></div>
<div class="color-picker-2"></div>
<span class="color-picker-1-outputs"></span>
</code>
</pre>
<pre>
<code class="javascript">
var color1 = 'hsla(282, 72%, 50%, 1)', color2 = 'hsla(228, 87%, 55%, 1)';
// Listen to the 'newcolor' event and use the new color to update things
// The event is emitted from the color picker DOM element
$('.color-picker-1').colorpicker({ color: color1 });
$('.color-picker-1').on('newcolor', function (ev, colorpicker, component, value) {
// Print some of the arguments that comes with the newcolor event
$('.color-picker-1-outputs').html(
'new color: ' + colorpicker.toString('rgba') + ', ' +
'component: ' + component + ', ' +
'value: ' + value.toFixed(3));
// Store the new color in a variable
color1 = colorpicker.toCssString();
updateBackground();
});
// As a convenience, we can also call .on() directly on the color picker instance.
// This is the exact same thing as calling $('.color-picker-2').on('newcolor', ...)
var colorPicker2 = $('.color-picker-2').colorpicker({ color: color2 });
colorPicker2.on('newcolor', function (ev, colorpicker, component, value) {
color2 = colorpicker.toCssString();
updateBackground();
});
// Set initial background color
updateBackground();
</code>
</pre>
<h2>
Live demo
<a href="examples/listening.html" target="_blank">Show standalone</a>
<a href="examples/listening.html" class="full-source">View full source</a>
</h2>
<iframe src="examples/listening.html" frameborder="0" class="live-example"></iframe>
</section>
</article>
<article id="theming">
<h1>Theming and styling</h1>
<section>
With just a few lines of CSS, the entire appearance of the color picker can be altered. Internally, all sizes are specified using the <code>em</code> unit, which makes it very easy to adjust the size of the whole color picker. The jColor color picker root element always has the CSS class <code>colorpicker</code> and it is good practice to use that as a namespace for all your custom CSS rules.
</section>
<section>
<section>
<pre>
<code class="xml">
<div class="color-picker-themed"></div>
</code>
</pre>
<pre>
<code class="javascript">
$('.color-picker-themed').colorpicker({ color: '#4bdb80e9' });
</code>
</pre>
<pre>
<code class="css">
/* Setting the font size of the root element scales the entire color picker */
.colorpicker.color-picker-themed {
font-size: 1.3em;
}
/* Remove all shadows, for a more flat look */
.colorpicker.color-picker-themed * {
box-shadow: none;
}
/* Remove the border when minimized and make the background transparent */
.colorpicker.color-picker-themed .maximize-wrapper {
padding: 0;
background: transparent;
}
/* Give all the components gray borders */
.colorpicker.color-picker-themed .display-wrapper,
.colorpicker.color-picker-themed .slider {
box-shadow: 0 0 0 0.05em rgba(64, 64, 64, 0.5);
border-radius: 0.1em;
}
/* Show overflow, so that the borders specified above won't get cut off */
.colorpicker.color-picker-themed.expanded .inner-maximize-wrapper {
overflow: visible;
}
/* Make sure the slider handles matches the gray borders */
.colorpicker.color-picker-themed .slider .handle {
background: rgba(64, 64, 64, 0.5);
box-shadow: none;
width: 0.2em;
margin-left: -0.1em;
}
</code>
</pre>
<h2>
Live demo
<a href="examples/theming.html" target="_blank">Show standalone</a>
<a href="examples/theming.html" class="full-source">View full source</a>
</h2>
<iframe src="examples/theming.html" frameborder="0" class="live-example"></iframe>
</section>
</article>
<article id="cleanup">
<h1>Cleanup</h1>
<section>
Creating and destroying a color picker works in the same way as most jQuery plugins, just call <code>.destroy()</code> on an instance to remove it and restore the host element to it's original state.
</section>
<section>
<pre>
<code class="xml">
<div class="color-picker-destroy-me" style="color: lightseagreen;">[placeholder]</div><br>
<button class="create-btn">Create</button>
<button class="destroy-btn">Destroy</button>
</code>
</pre>
<pre>
<code class="javascript">
$('.create-btn').on('click', function () {
$('.color-picker-destroy-me').colorpicker();
});
$('.destroy-btn').on('click', function () {
$('.color-picker-destroy-me').colorpicker().destroy();
});
</code>
</pre>
<h2>
Live demo
<a href="examples/cleanup.html" target="_blank">Show standalone</a>
<a href="examples/cleanup.html" class="full-source">View full source</a>
</h2>
<iframe src="examples/cleanup.html" frameborder="0" class="live-example"></iframe>
</section>
</article>
<div class="full-source-modal" style="display: none;"></div>
</body>
</html>
?>