redshift-jquery

jQuery plugin for Redshift

Plugins for aiding Redshift use with jQuery selections. When any plugin is called, we loop through each element in the jQuery selection and check if it has an associated Action. If it doesn't, we create one.

When an Action is created using a jQuery plugin, we automatically overwrite the scope property with its associated jQuery element. This means that within callbacks, this will refer to its jQuery object.

Install

NPM + Browserify (recommended)

First install the Redshift jQuery plugin in your project root.

$ npm install redshift-jquery

Then include in your module using require().

var $redshift = require('redshift-jquery');

Because we're now in the modular world, the Redshift jQuery plugin won't automatically have visibility to jQuery or Redshift. So, we run its .load() method and pass through our jQuery and Redshift references, like so:

$redshift.load(jQuery, redshift);

File include

Download the latest redshift-jquery.global.min.js from http://github.com/InventingWithMonster/redshift-jquery and include it in your HTML document with a script tag.

Important: Make sure you load the plugin file after jQuery and Redshift. When the plugin file loads, it will check the global scope for window.jQuery and window.redshift and use those to run .load().

<script src="/path/to/redshift-jquery.global.min.js"></script>

Use

After loading the jQuery plugins for Redshift, you'll have access to .action(), .play(), .track() and .run() methods on any jQuery selection.

Because a jQuery selection might consist of multiple elements, and each element is given its own Action, the return value will be an Array if more than one Action is fired.

.action()

The main interface to an element's Action. Calling .action() without arguments will return that element's Action.

By passing through a string of an Action method, we will call that method. Subsequent arguments will be passed through to the method.

// Single element example
var $single = $('#myElement');
 
$single.action(); // Creates and returns a new Action with scope property = $('#myElement')
$single.action('setProp', 'foo', 'bar'); // Sets Action property 'foo' to 'bar', returns element Action
$single.action('getProp', 'foo'); // Returns 'bar'
 
// Multiple element example
var $multiple = $('.myElements');
 
$multiple.action(); // Returns [Action, Action, ...]
$multiple.action('setProp', 'foo', 'bar'); // Sets all Actions property 'foo' to 'bar', returns [Action, Action, ...]
$multiple.action('getProp', 'foo'); // Returns ['bar', 'bar', ...]

.play(), .track(), .run()

Play, track and run are the primary methods for making Actions actually do stuff, so they each have a shorthand plugin. These act exactly like .action() except the function name serves as the first argument (the method name). So you can call them exactly as you would on a normal Action, ie:

$single.play({
    values: {
        x: {
            to: 100
        }
    },
    ease: 'easeInOut',
    onChange: function (output) {
        this.css('transform', 'translate3d(' + output.x + 'px,0,0)');
    }
});