colorRoller | jQuery Plugin

$.colorRoller()RC

a jQuery ThemeRoller plugin


New Features
[ ver. 0.1.1 | 2017-02-21 ]

  • jQuery 3.x support

    This version has been updated to work with the latest version of jQuery (3.x)

  • External source support [php required]

    Specify a jQuery theme that's hosted on a different server or domain. fetchCSS documentation


Upcoming Features

  • Support for script minification

    Currently this plugin requires a seperate un-minified theme to work. In future we'll add support for minified versions of jQuery UI themes.

  • CSS generator

    Load an external jQuery theme to extract colors and generate css that you can use on your site.

$.colorRoller Documentation ver. 0.1.1

2017-02-21

Requirements (for RC release)

  • jQuery Core

    $.colorRoller was written using jQuery core ver. 3.x
    Further releases of this plugin will be tested and optimized for older versions of jQuery Core.

    <script type="text/javascript" src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.1.1.min.js"></script>

    [ using MSDN CDN as our library hosts ]

  • jQuery UI

    As the plugin is in RC stage, it's been tested with jQuery ver. 3.x and jQuery UI ver. 1.12.1

    <script type="text/javascript" src="https://ajax.aspnetcdn.com/ajax/jquery.ui/1.12.1/jquery-ui.min.js"></script>

    [ using MSDN CDN as our library hosts ]

  • jQuery UI theme

    $.colorRoller requires at least one un-minified ThemeRoller theme to be linked in the page <head> tag.

    <link rel="stylesheet" type="text/css" href="/css/custom-theme/jquery-ui.theme.min.css"/>
  • [ example theme -
    view theme on ThemeRoller ]
    [ default theme-name folder:
    custom-theme ]
    $.colorRoller default folder

Installation

  1. Download the $.colorRoller plugin and upload to your server.
  2. Roll a theme with jQuery ThemeRoller and copy the theme folder to your server
  3. Add jQuery Core, jQuery UI, your ThemeRoller theme and colorRoller plugin to the page head
  4. example head scripts

Basic Usage

Call $.colorRoller(); on $(document).ready

$(document).ready(function() { $.colorRoller(); });

[ $.colorRoller assumes your css theme name is custom-theme . ]
[ If not, it can manually specified as an option - see advanced section ]

exposed classes

$.colorRoller() will create four classes for each section of the ThemeRoller

(1) Background color (expressed as css background-color:#hex )
(2) Border color (expressed as css border:1px solid #hex )
(3) Text color (expressed as css color:#hex )
(4) Icon color (expressed as css color:#hex )

:hover pseudo-classes are automatically added for Clickable: hover state (see below)

class Example

The following classes are written to the page head after $.colorRoller() has successfully loaded.

Background
Border
.bgColorHeader .borderColorHeader
.bgColorContent .borderColorContent
.bgColorDefault .borderColorDefault
.bgColorHover .borderColorHover
.bgColorActive .borderColorActive
.bgColorHighlight .borderColorHighlight
.bgColorError .borderColorError
.bgColorOverlay  
.bgColorShadow  
Text
Icon
.fcHeader .iconColorHeader
.fcContent .iconColorContent
.fcDefault .iconColorDefault
.fcHover .iconColorHover
.fcActive .iconColorActive
.fcHighlight .iconColorHighlight
.fcError .iconColorError
   
   

Advanced Options

The options below will enable you to add additional themes and custom folder structures:

  • themeName:'your-theme-folder-name'
    [ default: 'custom-theme' ]

    When using ThemeRoller, the default themeName is "custom-theme". If you include the theme css file from within the "custom-theme" folder, $.colorRoller will automatically find the theme.

    For any other theme names, (including secondary themes), pass in the folder name as an option:

    $.colorRoller({themeName: 'your-theme-name'});
  • cssScope:'cssScope'
    [ default: '' ]

    When using ThemeRoller's css-scope functionality, you can tell $.colorRoller to scope its css output by adding the following option:

    $.colorRoller({themeName: 'your-theme-name', cssScope: 'your-css-scope'});

    [ note: no preceding '.' on the scope name ]

  • themeUrl:'/your-css-folder/your-theme-folder/your-theme-css-file.css'
    [ default: '' ]

    If you prefer not to use ThemeRoller's default folder structure, you can pass your theme's full src-url to $.ThemeRoller. When adding this option, $.colorRoller will ignore the themeName option:

    $.colorRoller({themeUrl:'/your-css-folder/your-theme-folder/your-theme-css-file.css'});

.destroy() method

To unload ALL themes, call $.colorRoller.destroy();
To unload a specfic theme, call $.colorRoller.destroy('theme-to-unload');
The destroy() method also supports an optional callback function.

$.colorRoller.destroy(themeName,callback function(){});

Load colors from external CSS files [requires PHP]

Loading external css (i.e. not from your own domain) directly from your browser is riddled with browser security limitations. To overcome this, we can use PHP to fecth the file for us and pass it back to the browser. Now the css-file belongs to your domain and can be processed without security limitations.

$.colorRoller will automatically check themeUrl and evaluate if it's an internal or external url.

Requirements:
You need to be able to run fetchCSS.php for this feature to work. To specify location of fetchCSS.php on your server, pass it to $.colorRoller as an option (or alternatively, you can edit the default value in the plugin code)

$.colorRoller({themeUrl: "http://site.com/themeSrc.css", themeName: "remote-theme", cssScope: "css-scope", fetchCSS: "/your/server/fetchCSS.php"});

Options:
themeUrl: Absolute url to your external ThemeRoller css source
themeName: Specify a theme name. [ default is "custom-theme" ]
cssScope: Optional, css scope prefix [ default is "" ]

Security:
fetchCSS.php does a referer check as well as a file type check to avoid 'relay-abuse'. This means that only your site will be able to access fetchCSS.php and will only fetch .css files.


dev Mode

Dev mode will output on-the-fly class examples and computed css to the screen when set to true.

$.colorRoller({devMode:true});
Dev Mode Css examples
Dev Mode Style examples

colorRoller DOM object | Hex-colors available at runtime

$.colorRoller creates a DOM object containing the hex colors for each theme loaded.
Hex colors can be retrieved after page load by calling a className from the colorRoller DOM object:
[ Note: the DOM object is not accessed with a preceding "$.") ]

colorRoller['custom-theme'].uiHex.bgColorHeader -> '9fda58'
$.colorRoller DOM object example

The colorRoller DOM object is created when $.colorRoller successfully loads.
This means that calls to the DOM object ON PAGE LOAD need to go in the callback function function.
Calls from e.g. buttons (after page load) can be done with a regular jQuery/JavaScript call.

Usage License | Feedback | © 2017 - Francois du Plessis
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
Creative Commons Licence