jQuery Plugin: EffectChain v1.0

Sat, 13/09/2008 - 20:39 — DuMmWiaM

In jQuery all effects are applied simultaneously, to all elements selected by the query, with EffectChain you can apply all jQuery effects (1.2+) in a chain (sequence). ALL effects are supported: hide, show, fadeIn, fadeOut, fadeTo & animate! Moreover with EffectChain you can shuffle the order of the effect on the DOM elements (reverse or random), setup delays between the application of the effect to an element plus many more features, and all these with a minimal footprint!

Installation

In order to work you need the jQuery library (version 1.2.+) and the javascript file of the EffectChain. Once you have them, link them inside the head of your html file:

<script type="text/javascript" src"folderName/jQuery.js"> </script>
<script type="text/javascript" src="folderName/EffectChain.js"> </script>

don't forget to replace "folderName" with the folder that you've stored the two ".js" files.

Compatibility

jTypeWriter has been test for compatibility issues with the following broswers:

Internet Explorer 6+
Mozilla Firefox 2+
Opera 9+
Safari 3+
Google Chrome
iPhone Safari, a little bit slow, bit it works :).

Probably it will work, with earlier versions of Opera and Safari, but I haven't try it out.

Usage

To properly use the EffectChain plugin, you must first make sure that the DOM is ready to be traversed and manipulated. To acheive that the code of any EffectChain implementation must reside inside the event ready. For example let's assume you want to apply the EffectChain effect in a series of elements: <div class="box> and you want to make them disappear in 3 seconds (each).

<script language="javascript" type="text/javascript">
$(function() {
$('.box').EffectChain({duration:3});
}
</script>

An alternative way to achieve the same thing, is to ensure that the EffectChain is placed after the DOM element that you want to handle. Although it's not the "appropriate" way, you could do it (for example the Google analytics javascript code, is placed before the end of the <body>).

...html...
<script language="javascript" type="text/javascript">
$('h1 #title').jTypeWriter({duration:1.5});
</script>

EffectChain Parameters

EffectChain plugin can accept 6 different parameters that can change the effect applied to the DOM elemets that are selected. Don't forget that the same effect will be applied to all DOM elements selected with EffectChain:

duration: [number] default : 1
The duration of the effect for each element in seconds. The total duration will depend on the number of elements you will select with jQuery.
The default value of this parameter is: 1 (second).
order: [string->"normal","random","reverse"] default : "normal"
The order in which the effect will be applied to the DOM items selected.
The default value of this parameter is: "normal".
effect: [string->"hide","show","fadeIn","fadeOut","fadeTo","slideDown","slideUp","animate"] default : "hide"
The official jQuery effect you want to apply to the elements. Currently EffectChain supports: hide, show, fadeIn, fadeOut, fadeTo, slideDown, slideUp and animate.Appart from "fadeTo" and "animate" all other parameters are used no extra requirements, you just type the name of the effect (casesensitive string) you want ot apply.
In case you want to use the "fadeTo" effect, you must also provide the fadeToOpacity parameter, which a numeric value from 0 to 1 for the opacity of the element.
In case you want to use the "animate" effect, you must also provide the animateParams parameter, which is an object for various custom animation parameters (CSS based).
The default value of this parameter is: "hide".
delay:[number] default : 0.
The amount of delay in seconds, that will be applied between the elements.
The default value of this parameter is: 0.
onStep: [function] default : null]
This function (event) will be called/fired when the effect has been on each element. So...if you want something to happen everytime the animation completes in an element, pass the name of the function(without the brackets).
The default value of this parameter is: null.
onComplete: [function] default : null]
This function (event) will be called/fired when the effect has been applied to all elements. So...if you want something to happen when everything completes, pass the name of the function(without the brackets).
The default value of this parameter is: null.Which means no function will be executed at the end of the effect on all elements:).
fadeToOpacity:[number 0.0 ->1.0] default: 0.1.
This parameter must be provided if you pass "fadeTo" to the effect parameter, else it will be ignored. This parameter represents the opacity (alpha) for the effect, that will be applied to the element..
animateParams:[object] default: null.
This parameter must be provided if you pass "animate" to the effect parameter, else it will be ignored. By providing an object with CSS properties and values you can create custom animation effects on each element. The suggest usage is: $("elements").EffectChain({effect:"animate",animateParams:{ property1:"stringValue", proptery2:numericValue, .., propertyX:"value value value"}});
For example: {width: "70%", opacity: 0.4, marginLeft: "5px", fontSize: "3em", borderWidth: "10px"}.

Suggest Usage

EffectChain is a very versitile improvement on the jQuery effect engine. It enables you to animate a series of same objects, let's say products or news in your page.

Let's assume that in your first page of your website you have some 9 <div class="box"> elements that contain inside them your most famous products/books/articles/software etc and you want to present them in a nice way...let's say fade in, then your code will be: $('div.box).fadeTo(0,0).EffectChain({effect:"fadeTo",fadeToOpacity:1});

I believe that with the correct use of CSS the possibilities and combinations are endeless.

Examples

Example A : Simple usage

Use of EffectChain, without any parameters to a series of div elements. Without any parameters passed to EffectChain, you have a hide effect to all elements, in normal order and the duration is 1 second for each animation. A very importan think to note is that, the jQuery selector must "collect" more than one elements. In the examples bellow I give all <divs> the same class name.
CODE: $('.exampleA').EffectChain();

Container 1
[example A]

Container 2
[example A]

Container 3
[example A]

Container 4
[example A]

Container 5
[example A]

All divs have the same class name:"exampleA", thus the selectors is $(".exampleA").

Example B : Custom Duration, Delay, & Show Effect.

If we set the duration parameter to 2.5 the animation effect of each item will last for 2.5 seconds.
By setting the delay parameter to 1 we force a 1 second delay between the effect of each element.
Finally in this example we set the parameter effect to "show", in order to display the items, that are hidden. In the code bellow you will see that I use jQuery to instantly hide the items and then apply EffectChain, all in one line of code!
CODE: $('.exampleB').hide().EffectChain({duration:2.5,delay:1,effect:"show"});

Container 1
[example B]

Container 2
[example B]

Container 3
[example B]

Example C : OnStep & OnComplete Events

EffectChain comes with two types of events (functions), that can be fired when each effects ends and a final events, when all effects have completed.
The OnStep function fires each time an effect is completed in an element. If we have 4 elements, a function will be fired 4 times. The OnComplete function fires once, after all effects are complete.
For simplicity's sake, I place the functions for both events inline to save space. When you use it, I suggest to assign a referance to the functions name.
CODE: $('.exampleC').hide().EffectChain({effect:"fadeIn",onStep:function(){alert('step');},onComplete:function(){alert('complete');}});

Container 1
[example C]

Container 2
[example C]

Container 3
[example C]

Example D : Change the Order of the EffectChain

The default display order of the effect is the one used by the DOM tree. If you want to change that, you can set the order parameter to either: "reverse" or "random". If you do that, then the effect will not be shown in the DOM tree order, but the one you have set.
CODE: $('.exampleD').fadeTo(0,0).EffectChain({order:"random",effect:"fadeTo",fadeToOpacity:0.8});

Container 1
[example D]

Container 2
[example D]

Container 3
[example D]

Container 4
[example D]

Container 5
[example D]

Container 6
[example D]

Container 7
[example D]

Container 8
[example D]

Download

You can download a set of files, full of working examples. Click bellow to download it!

Download EffectChain v1.0 examples!

ChangeLog

14 SEPT 2008: version 1.0 released

License

EffectChain is released under GPL Open Source Licenses...thus it is completely and totally free!. You are obligated to keep all credits (links, names etc) and if you feel like it a link to this page will be appreciated!

jQuery

Comments

Sat, 01/11/2008 - 09:17 — mcgyver (not verified)