Creating Custom Effects in jQuery

The other day I needed to create a custom effect in jQuery but I couldn’t find decent documentation on how to do it. I resorted to reading through the jQuery UI effects source code to figure it out, and while that’s fine, in case you’re looking to do the same thing (create a custom effect, not read through source code), I figured I’d write a post to at least speed up your development effort.

All of the effects follow the same basic layout: a self-contained function that extends the $.effects namespace with the name of the effect (e.g. $.effects.myEffect) as a function that takes a single parameter (‘o’, that contains all of the options the user of your effect passes in via the call, and some other information that jQuery stuffs in there).

Inside this function, you basically just return the result of doing this.queue(); (which takes a single parameter – a function). That call enqueues your effect into the jQuery animation queue. The code inside the queue call also follows the same basic structure: set up your effect properties, declare the CSS properties you want to set back to their original values (the jQuery UI infrastructure has a nice function pair [$.effect.save()/restore()] for saving and restoring CSS properties so that whatever element your effect was invoked on is returned to the visual state it was in before your effect was run), and then set up a loop to run your animation the number of times requested by the user of your effect. If the effect is the kind that you’d only run once (e.g. fade), you don’t need/want the loop. Regardless, you then call $.animate() to perform your custom animation, as necessary. A skeleton effect might look like this:

/** 
 * jQuery effect plug-in skeleton. 
 */ 
(function($, undefined) { 

$.effects.myEffect = function(o) { 

   return this.queue(function() { 

        var $this = $(this),  
            props = [ 'background-image' ], 
            times = o.options.times || 1, 
            duration = o.duration || 1000; 

        $this.css('percent', 0); 

        for (var i = 0; i < times; i++) { 
            // Call $this.animate() as necessary to perform animation for your effect. 
        } 
    }); 
}; 
})(jQuery);

This should be enough to get you started creating your own custom effects. One thing to note: in your last call to animate, you will want to make sure you set up a callback function, and in it, call $this.dequeue() or else your animation will never start, or else start the animation after the last animate call if your effect can’t be chained. That would also be where your restore the CSS properties you saved with $.effects.save() (line 15). For example (note: this is for a chained effect, you’ll want to animate with queue: false for this kind of effect, see the animate method’s documentation):

// Last animate call in the effect 
$this.animate({ /* Whatever */}, { 
    complete: function() { 

        $.effects.restore($this, props); 
        $this.dequeue(); 

        if (o.callback) { 
            o.callback.apply(this, arguments); 
        } 
    } 
});

In an upcoming post, I will show how I created two custom effects that jQuery’s animate() function doesn’t natively support (linear-gradient and box-shadow) using the step parameter in the animate method.