Domino Effect

Repository hosted on GitHub

KHI End User License Agreement:

I’m sure you don’t like reading these stupid things any more than I like writing them, so we’ll keep it short and sweet:

This software is provided to you, for your own personal, private use, without any kind of warranty or promise of support whatsoever.
You are licensed to use this software, not to distribute it or sell it. I ask that you please not mirror any files which I have not explicitly relinquished my exclusive copyright to anywhere without prior authorization.

Sound cool to you?

Accept Decline

Every year or two somebody builds another DSL on top of JavaScript that tries to make you forget about the fact that it’s still JavaScript and it’s still terrible. The current industry darling is jQuery, and by and large, it’s really a pretty well thought out framework / library / whatever. Unfortunately, it has no concept of global effects queues, which makes sequential effects across multiple DOM elements a royal pain in the patootie.

Domino Effect is not an all-purpose effects queue, but a lightweight solution to one very basic and very common problem: running a single effect on multiple elements one-by-one, as if they were a carefully laid out stack of dominos. You just build a jQuery object based on a selection and call one function that sets them all up as a stack. As long as you don’t need anything fancier, all the messy callback chains are handled for you.

Example:

黒豚黒豚黒豚黒豚黒豚

WebKit browsers will display fancy 3D transitions
FireFox will just run the fades

d = jQuery("#parent > ruby").domino_effects("_fade", { L2R: tip_forward, R2L: tip_back });

function tip_forward(cb) { this.addClass("inverted").fadeTo(200, 0.7, cb); }
function tip_back(cb) { this.removeClass("inverted").fadeTo(200, 1.0, cb); }

jQuery("#domino_button").click(flip_dominos);

Here we select all the immediate children of #parent which are of type ruby and setup a domino stack. This requires two pieces of information: a name and an object literal containing at least one of L2R and R2L. The name is a completely arbitrary string used to identify this stack, but each member of the object literal must be a function that describes what each domino element does when it is tipped—in this case, add a class named inverted and execute a fadeTo.

These functions receive a single parameter, a callback, which should be passed off to whatever the last effect in the chain is going to be. The keyword this will be bound to a jQuery object representing the DOM element that is currently being tipped.

Finally, we bind an event handler to a button which does the flipping.

function flip_dominos()
{
    var state = dominos._fade_dominos_state;
    
    jQuery("#domino_button").attr("disabled", "disabled");
    
    if ( !state )
        dominos._fade_dominos_L2R(enable_button);
    else if ( state == 1 )
        dominos._fade_dominos_R2L(enable_button);
    
    function enable_button()
    {
        if ( dominos._fade_dominos_state )
            jQuery("#domino_button").attr("value", "Reset Dominos");
        else
            jQuery("#domino_button").attr("value", "Tip Dominos");
            
        jQuery("#domino_button").removeAttr("disabled");
    }
}

First, notice that the stack contains a method called _fade_dominos_state. _fade is the name we chose for this stack when we created it, and _dominos_state was generated automatically. This is a handy way to check what state the stack is in. If it’s just been setup, it will be undefined. If it’s been tipped forward, it will be 1. If it’s been tipped back, 0. If it is actively tipping, you’ll see a -1 here, and should not attempt any additional tips unless you want some unpredictable results. This plugin is not reliably reentrant!

When we want to flip the stack forward, we call an automatically generated method on the stack which consists of the name we chose when we created the stack up above, _fade, plus _dominos_L2R or _dominos_R2L. These functions take an optional completion callback which will be executed after the last or first, depending on the direction we’re going domino in the stack tips. Here we just want to re-enable the button.