FAQ

What is $fx() library?

$fx() is a tiny, self-contained Javascript library for animating HTML elements. It doesn't require any other library to function and [should] play well with any other libraries you are using (Prototype, JQuery, Moo tools, etc.)

$fx() allows you to alter any CSS property along a timeline, allowing animated effects to play in succession — i.e. in the order you want them to. It handles all of the headaches of timer controls and makes it easy to animate anything from simple, subtle animations (see the clouds on the front page) to more elaborate animations (send in your example to get it linked here!).

$fx() also offers the ability to combine adjustments to CSS properties for combined effects, and allows you to set multiple callbacks, offering more flexibility.

Why should I use $fx()?

... when there are so many other Javascript libraries to choose from? Simple. In a community where Javascript libraries are like free samples at Costco, it can be hard to choose just one. Most major Javascript libraries offer a huge list of features and effects that give you the ability to do just about anything in a browser that you could ever want. Unfortunately, with such a broad scope, you will often find that a great deal of the library will go unused and — furthermore — if you're just looking for some sweet animations, then you wont need 20k-60k of extra Javascript code offering things like AJAX controls, object-oriented elements, etc. You just want animation.

The reason you should use $fx() is that it's tiny and doesn't require any other library to function. With an additional 4k (small enough that even a 14.4bps modem from 20 years ago could download it in 3.5 seconds) for your site, you can be animating elements without needing to depend upon Flash, Silverlight, etc. an can stick to what you do best: making websites!

How did $fx() come to be?

I looked around on the internet to find a simple Javascript animation library (much like you were, probably) and found that every option required tens of K just for the library, and that the vast majority of the features they offered were features I didn't need. Many of these Javascript libraries were larger than the entire site I was working on (including graphics!) which seemed unnecessary to me.

So, I set out to give the world something it desperately needed: a tiny, efficient, fast, simple and easy to use Javascript animation library. Soon afterward, $fx() was born.

Now, $fx() is not here to compete with any other Javascript Library, it's simply here to fill a gap.

Can $fx() do ______?

If it involves animating DOM elements by altering CSS properties on a timeline, then probably yes. If not, then with your feature request, and I'll see what we can do!

If you want to share some ideas on how to make $fx() better, or have if you have any questions or comments, then and I'll reply as soon as I can.

Available methods

$fx()

$fx(element) —the primary class, which extends an element with the fxAdd(), fxAddSet(), fxHold(), fxPause(), fxReset(), fxRun(), fxStop() methods to describe and run effects, and contains an internal _fx property which contains the whole animation processing logic. (Basically, this is the Big Kahuna. You need this one.)

element — can either be a DOM element, or element id passed as "#elementId".

Returns modified DOM element. All added fx* methods return elements themselves.

fxAdd()

fxAdd(params) — adds a new effect to the current set. The effects wont run immediately, but will be added to your animation set. The entire set will run after the fxRun() call is made.

params object sets animation parameters. Required set of fields to be defined:

1. type — type of animation effect. The type paramter is same as the CSS property name for a DOM element. So, to alter the X-Coordinate of an element, the type needs to be set to 'left'. Other properties you can alter are:

   opacity — cross-browser property to adjust an element's opacity.
   backgroundx — background X position.
   backgroundy — background Y position.

2. from — initial value for property defined in type. This parameter is optional. If it hasn't been defined then property will be retrieved from style property (style="property:value"). If style property is not defined in HTML then effect won't be applied because of insufficient parameters (an animation needs a starting point!). Some methods have special needs: Opacity attempts to get value from element.style.filter in Internet Explorer and reads element.style.opacity property for all other browthers. Backgroundx and backgroundy retrieves values from element.style.backgroundPosition. Left, top, width and height aren't retrieved from style properties, so it's not neccesery to define left, top, width, or height in the element's style attribute.
3. to — end property value. Once it has been reached, the effect stops running.
4. step — positive or negative integer value to alter a CSS property, per one iteration (i.e. step).
5. delay — delay between iterations in miliseconds. This parameter is optional, by default it is 100. Do not set this number too high, unless you want choppy animation.
6. unit — optional paramter to define mesurement units for a certain CSS property. If unit wasn't defined, then it will be picked by type value: left, top, right, bottom, width, height, margin, padding, spacing, backgroundx, backgroundy - px; font - pt; no unit for all other properties.
7. onstart — function called before effect starts. You can use this object inside callback, which references to the element.
8. onfinish — same callback as onstart but runs after affect is complete.

fxAddSet()

fxAddSet() creates new set of effects which starts running parallel fxRun() calls. You don't need to call this method initially because $fx() calls it internally.
So this statement:
$fx('#someElm').fxAdd(ani1).fxRun().fxAddSet().fxAdd(ani2).fxRun();
is absolutely identical to
$fx('#someElm').fxAdd(ani1).fxRun();
$fx('#someElm').fxAdd(ani2).fxRun();

fxHold()

fxHold(delay) — sets the delay to wait in miliseconds before all effects in current set start.

fxPause()

fxPause(status, [setNum]) — pauses (status=true) or starts (status=false) set with index setNum. If setNum wasn't defined then method will be applied to the last set that was created.

fxStop()

fxStop([setNum]) — stops the set with index setNum. If setNum wasn't defined then method will be applied to the last set created.

fxReset()

fxReset() — stops animation and deletes all animation handlers and methods added to the element by $fx() also all CSS properties will be set to their initial values. This is the reset button.

fxRun()

fxRun(finalCallback, loops, loopCallback) — starts the effects set. All three parameters are optional. finalCallback is the funtion called when all loops of the current set are complete. loops sets the number of loops current set to be repeated, set loops to -1 to run set with infinite count of loops. By default loops is 1. loopCallback function to be ran on single loop complete. Both finalCallback and loopCallback callbacks can use this as a reference, which then references to the DOM element you are running the effects on.
You can pass null to keep parameter undefined. For example, write element.fxRun(null, -1) to cycle effect set without defining any callbacks. Handy, huh?

Examples

How to add and run single, simple effect

First you will need an element. Any element will do (let's assume it's: <div id="myDiv">). You then call $fx() and pass reference to the element as described above.

$fx('myDiv')

Then, you can add effects by calling to $fxAdd(...).

$fx('myDiv').fxAdd({type: 'fontSize', from: 12, to: 72, step: 1, delay: 20});

Then run it!

$fx('myDiv').fxAdd({type: 'fontSize', from: 12, to: 72, step: 1, delay: 20}).fxRun(null,-1);

How to run a more elaborate effect

You can follow the same steps of the basic animation example in order to do even the most elaborate of effects. So, let's hit the ground running and create a starfield, shall we?

We have two DIV's with same background image but different background-position properties. We will scroll backgrounds (alter background-position X and Y) from right to left width different speeds (for a Parallax Scrolling effect). As you can no doubt guess, background position animation is achieved by changing the backgroundx CSS Property.

To make cycled animations, we just run it with number of loops -1 (line 5,6). null, as you'll remember, means we are not defining any callbacks... we're just running the current animation set.

The fist DIV's background-X position is 0, so we wo;; scroll it to X=-314 and then bring it back to 0, so our animation will loop smoothly. But another one has initial background-X position of 45px, so it's end X coord should be -314 + 45 (or -269). $fx library doesn't take care of this [yet?], it just alters the settings you provide.

So, you will have to crunch a few numbers. ... oh, come on, it wouldn't be fair to do *all* the work for you!

Adding a set of parallel effects

So, we have our starfield. Now, let's add a spaceship, shall we?

Lines 1-6 are axactly same as in our previous example, so the stars animation is taken care of. In order ot add our spaceship, however, we'll have to add a few new effects (and some new elements).

ufoRotate scrolls the background image (the sprite with four sections)
ufoMove moves our little spaceship from left to right.
ufoAppear makes it to appear.

Once we call fxRun()

, the effects set gets closed and all following fxAdd() calls will add effects to the next set (which needs another fxRun() to start). You can see this in lines 9, 10.

Also, notice how we call fxAdd() twice in line 10? That means that those two effects will be running parallel to each other, so our spaceship appears and will keep moving at the same time. Pretty sweet, huh?

Callbacks usage examples

All callbacks are applied to the element you are animating, so it lets us use the this reference. Take a look at the lines 12-24. Go ahead. I'll wait.

At the line 12, we just get references to the message bubbles. Onloop and onfinish are handlers we will use as callbacks.

Easy enough!

License

The $fx() library is available under the MIT and GPL license, so you can choose whichever is most appropriate for your project. According to the license rules, full open source code is available.