Paletton Live Colorizer (BETA)

Use the Paletton.com engine on your own site. Let your users create a color palette by colorizing your own template.

This is a BETA (testing) version yet, use it with care.  ◆  A basic HTML, CSS and Javascript knowledge are required.

If you are not familiar with the Paletton.com application, try to play with it first. It is designed to create palettes of colors that work well together according to classical color theories.

The Paletton Live Colorizer allows you to use the Paletton engine within your own projects. Let your site's users to colorize a template, tables, sheets, web/page design, flyers, any creative graphic design, fabrics, decorations etc. To do that, easily insert the simplified version of the Paletton application to your project, and get the palette data as a javascript object suitable for storage or further processing.


This is how the Paletton Live Colorizer can look like in your own web page:

Colorizer preview

Open the live demo to see how the Paletton Live Colorizer works within a third party web page.

A sample web page opens. It contains the Colorizer javascript code (see bellow), and the widget action is attached to the "Colorize" button. Click the button to open the Colorizer widget. Feel free to play with the colors. When done, click the "Apply" button. The palette is actually not applied to anything, just the resulting Colorizer data is displayed in a readable form. If you click "Cancel" instead, an empty object is returned.

Demo 1 – Class-based colorizer Demo 2 – LESS colorizer Demo 3 – Custom JS

These are live demos of the Paletton Live Colorizer. To demonstrate the inter-domain communication, the demos are intentionally running on a different domain than the Paletton.com application..

Combination of HTML, CSS (or Less) and Javascript is required to add the Paletton Live Colorizer to your web site. You have to do following three steps to make it work.

1. Set up a Colorizer preview

A preview is a visual presentation of the color palette. Start by downloading the preview template and checking its code to see how it works. Then follow the step-by-step guide to Colorizer preview documents to learn how to create your custom preview.

2. Add Colorizer to your page

You have to link the Paletton's widget.js javascript into your HTML page. This makes the _paletton.open() method available for your scripts, and you can use it to launch the Colorizer at any time – typically as an link/button onclick handler.

See the details on adding Colorizer to your page below.

3. Use the Colorizer

There are two parts of the interaction with the Colorizer.

  1. First, you can launch it with various parameters. See guide to Colorizer options.
  2. When the Colorizer is done, you should process the data it sends to your page. See details on Colorizer result data.

A preview is a visual presentation of the selected color palette. It is a standard HTML document, located on your server.

As the user changes colors in the palette, the preview is colorized using the shades of the pallete. The preview could be a simple HTML page providing a preview of all typical color combinations of selected palette when used in your final product (a web page, a printed design, decorations etc.), or a sophisticated application capable to visualize received palette data in real time. It's completelly upon your choise, how simple or how rich your preview document is.

The best way to start understanding preview documents is to download following preview template, check its code, and see how it should look like and how it works.

Download demos with preview templates


Following text describes the step-by-step guide how to create Colorizer preview documents.

Step 1: Get the default palette for you preview

As there are many color palette variants, containg one to four colors, you would find quite difficult to map a generic palette to your template. Therefore, the Colorizer allows you to fix the palette type for each preview. Simply decide what model (1-color, 3-colors, 4-colors, with/without complement) will your preview use.

  1. Use the Paletton.com application to select a default palette for your preview.
  2. Check the URL in the browser and find the palette's UID value.
  3. Store the UID, you will use it as the initial palette for your preview.
  4. The color model will be fixed and the user will change only palette colors while the mapping to your preview will be kept unchanged.

Palette UID location

If you want to offer multiple different palette models to your users, create multiple previews with different initial palettes.

Step 2: Create an HTML document

Create a standard HTML document. Design it to show all typicall color combinations when it's colorized by the palette created by your users. Store the preview HTML document anywhere on your server, available to the internet. You will need its public URL.

Step 3: Add required scripts

Following javascript libraries have to be linked to the preview HTML to make it work as Colorizer preview.

The easiest way is to link these libraries from a public library servers (CDN).

Next, the colorize.js script must be linked directly from the Paletton.com server. Simply add following scripts to the HEAD section of your HTML:

/* The preview HTML document */
<head>
   ...
   <script src="http://ajax.googleapis.com/ajax/libs/jquery/2.1.0/jquery.min.js"></script>
   <script src="http://cdnjs.cloudflare.com/ajax/libs/less.js/1.6.1/less.min.js"></script>
   ...
   <script src="http://paletton.com/widget/js/colorize.js"></script>
</head>

If your site already uses a valid version of jQuery and/or Less, feel free to link it from your server or from another location. If you won't use the Less colorize mode (as below), you don't need to add the Less library.

A ready to use preview template HTML document is available. Feel free to download it and adjust to match your site.

Step 4: Style your preview document

There are three colorize modes available in the Paletton Live Colorizer. The colorize mode is specified in Colorizer options (see below).

Before you start, you'd better get familar with the palette structure produced by the Paletton.com application. Simply try and play with different palettes, then click the "Color tables" link in bottom right corner and see the result color tables, and also check the export to HTML or CSS. The Colorizer's palette data are very similar to them.

A. Class-based colorize mode

This is the default colorizing mode. Each time the palette is changed, the Colorizer engine searches for all elements with applicable classes, and applies the palette colors to their respective CSS properties.

Simply use Colorizer-specific HTML classes in your HTML code. These classes will apply colors from Colorizer palette to the HTML elements. There are three types of applicable classes for each color and for each shade variant, allowing you colorize background, foreground and border color of elements. If you need colorize pseudo-classes like :hover or use the CSS's cascade, you have to try the Less colorize mode.

Available class names syntax:

   [property]-[color]-[variant]
or
   [property]-[color]-lum-[variant]

[property] is one of following values:
   bgcol applies as 'background-color' CSS property
   col   applies as 'color' CSS property
   bdcol applies as 'border-color' CSS property

[color] is one of following values:
   pri   primary color
   sec1  secondary color #1
   sec2  secondary color #2
   compl complementary color

[variant] is an integer number 0 to 4
   0 is the main color variant
   1–4 are the other shade variant, in the palette native order

If the -lum- flag is used in the class name, then the shade variants are ordered by luminance. The [variant] value meaning is different in this case:

[variant] is an integer number 0 to 4
   0 is the highest luminance (lightest) color
   4 is the lowest luminance (darkest) color

The luminance-sorted palette may be useful if you need to maintain a color contrast, i.e. for background and foreground text, regardless how non-standard variations the user selects in the palette.

Colorizer classes examples
Class Result
class="bgcol-pri-0" sets the background-color CSS property to variant #0 (the main shade) of primary color
class="col-compl-4" sets the color CSS property to variant #4 of complementary color (if used)
class="bdcol-sec1-lum-0" sets the border-color property to variant #0 by luminance order (the lightest shade) of first secondary color (if used)
class="bgcol-pri-lum-2 col-pri-lum-0" sets the background-color to luminance-ordered variant #3 (the medium luminance) and color to variant #0 (the lightest shade), both of primary color

B. LESS colorize mode

Using LESS mixins is more convenient way to colorize the preview document. It also allows you colorize pseudo-classes (like :hover) and use the full power of CSS and LESS. If this colorize mode is used, the less.js library must be linked to the preview document, and there must be a LESS stylesheet containing color definition mixins linked as well. You should be familar with the Less stylesheet language to use this colorize mode.

<head>
   ...
   <link rel="stylesheet/less" href="colors.less" type="text/css">
   ...
   <script src="http://cdnjs.cloudflare.com/ajax/libs/less.js/1.6.1/less.min.js"></script>
   ...
</head>

With Less colorize mode, instead of using different classes for various CSS properties, the Less variables (mixins) are used as color values in any CSS property.

Available mixin syntax:

   @[color]-[variant]: color_value;
or
   @[color]-lum-[variant]: color_value;

[color] is one of following values:
   pri   primary color
   sec1  secondary color #1
   sec2  secondary color #2
   compl complementary color

[variant] & -lum-
   have the same meaning as in class-based colorize mode above

color_value
   use any color as default, it will be replaced by palette color onload.
Remember, all used mixins must be defined first in the Less stylesheet.
Less colorizer usage examples
/* color.less stylesheet */

/* first, define the mixins */

@col-pri-lum-0: '#000';
@col-pri-lum-1: '#000';
@col-pri-lum-2: '#000';
@col-pri-lum-3: '#000';
@col-pri-lum-4: '#000';

@col-compl-0: '#000';
@col-compl-1: '#000';
@col-compl-2: '#000';
@col-compl-3: '#000';
@col-compl-4: '#000';

/* then, use your mixins */

body {
   background: @col-pri-lum-4;
   color: @col-pri-lum-0;
}
a {
   color: @col-compl-0;
}
a:hover {
   color: @col-compl-4;
   background: @col-compl-1;
}

C. Custom javascript handler

If you are experienced in javascript, you can avoid the automatic colorizer and handle the palette by yourselves. This colorize mode gives you the freedom to use the palette values any way you want. If the user updates the palette, your custom javascript callback function within the preview document would be called. It's completey upon you how you'll handle the color values – you can generate some objects on-fly, draw an image in canvas, colorize a photo, whatever.

As the Colorizer communication between documents uses JS messages, your script in preview document has to listen to the message with ID 'palettonwidget/colorize/custom'. The Colorizer data (colorTable) is sent as data property of the event.data passed to the message. This means, you need to pass the event.data.data value to your handler. You may add listener i.e. this way (on document load or DOM ready):

window.addEventListener('message',function(e){
   if (!e || !e.data) return;
   if (e.data.id=='palettonwidget/colorize/custom') myColorizeHandler(e.data.data);
   },false);

function myColorizeHandler(colorTable) {
   // ... handle the color table...
}

The colorTable object is the same the Colorizer returns as a part of result object to your callback function. See the Colorizer result data for details.

You simply install the Colorizer to your page by adding the Paletton's widget.js script to your code.

/* Any HTML document */
<head>
   ...
   <script type="text/javascript" src="http://paletton.com/widget/js/widget.js"></script>
   ...
</head>

Once the script is loaded, the _paletton object is available to your page. All you need is to use its method _paletton.open to launch the Colorizer.

This method requires two arguments: _paletton.open(options,callback)

Feel free to call the _paletton.open function any time to launch the Colorizer. The typical use would be adding it as an onclick handler to a link/button in your page.

Colorizer launch examples
...
<a href="#" id="colorize-button">Colorize my account</a>
...

<script>
   function storePalette(result) {
      // ... see processing results below...
   }
   
   var options = {
      // ... see options below...
   }
   
   var link = document.getElementById('colorize-button');
   
   link.onclick = function(e){
      e.preventDefault();
      _paletton.open(options, storePalette);
   }
</script>

The options object is passed to the Colorizer when it's opened. Its required values specify the Colorizer behavior, and the optional values override its default values.

options: {

// Editor options

   width: integer; optional; default = 960
   // Colorizer editor width in pixels, min width 640
   // (the palette editor is 420px wide, the rest is for preview)

   height: integer; optional; default = 500,
   // Colorizer height in pixels, min. height 500

   dark: boolean; optional; default = false
   // the Colorizer UI style: false = white Colorizer UI, true = dark Colorizer UI

// Preview template

   templateURL: string; required; default = ''
   // the URL of your preview HTML document.
   // A full URL must be provided, i.e. 'http://example.org/templates/template-01/index.html'

   paletteUID: string; required; default = ''
   // the UID of init palette as provided by the Paletton.com application

   paletteUIDdefault: string; optional; default = ''
   // the UID of default palette to be used for reset action. If omitted, the init value is used instead.

   colorizeMode: string; optional; default = 'class'
   // the colorize mode (see above), possible values = "class" | "less" | "custom"

// Various

   myData: any; optional; default = null
   // any user data to be passed-through within the results object
   // if the value is an object, it must not contain functions (nor any value that cannot be cloned)

}

From above, you can see the options object must contain at least templateURL and paletteUID, all other properties are optional.

When the user is done with the Colorizer and clicks the "Apply" button, the Colorizer is hidden and a result data object is passed to your callback function. The structure of the result object passed to the callback function is as follows:

{
   "colorTable": object {
      "byPalette": object {
         "pri":   array [0..4] of string as rgb hexcode, i.e. "#3699A0"
         "sec1":  array [0..4] dtto || null
         "sec2":  array [0..4] dtto || null
         "compl": array [0..4] dtto || null
      },
      "byLum": {
         "pri":   array [0..4] of string as rgb hexcode, i.e. "#3699A0"
         "sec1":  array [0..4] dtto || null
         "sec2":  array [0..4] dtto || null
         "compl": array [0..4] dtto || null
      }
   },
   
   "paletteUID": string; the result palette UID,
   
   "myData": object; pass-through user data as defined in options
}

The byPalette property contains color variants in palette-native order, while the byLum property contains colors sorted by luminance (as described in previous colorize modes). Only "pri" (primary) color is applied always, the other colors may be null if the respective color is not used in the palette.

If the user clicks the "Cancel" button, the callback function is called with a null value of the results object.