Introduction

I did this framework first of all for personal use. I could not find what I needed in script.aculo.us and honestly, I do not see any activity in script.aculo.us or scripty2 (alpha version of script.aculo.us 2)

I like also jQuery when I need to just have animation. But as I use a lot Prototype to build complex web applications, I needed something based on this powerfull JS Framework.

So ProtoFX is born :)

It’s a light weight animation framework (base version is less than 7Ko packed) with great features. I decided to use music semantic for class names. Running effects is like playing a song isn’t it?. The object in charge of time synchronization is called Metronome. The “queue” system (I will describe it later, but it’s more powerfull than a classical queue system) is called Score.

Actions are like music player actions: play/stop/reverse/rewind…

But let’s talk about ProtoFX features.

Features

Easy to use

I tryed to make an API really easy to use. You just need to chain methods on an effect object. For example to fade an element, just do:

   1  new FX.Element(element).animate({opacity: 0}).play();

If you need to set some options like duration just call setOptions function in chained methods.

   1  new FX.Element(element).setOptions({duration: 2000}).animate({opacity: 0}).play();

Pretty simple!

Actions

As I said before, actions are like using a music player. You can do:

• play
• stop
• reverse (even if the effect is running, call reverse and your animation will run backward)
• rewind. Next time you call play it will play from the beginning

Delta

Sometimes you do not know exactly where is your element in the page, you just want to move it of XX pixels to the left. You can use operand +=, -=, /= and *= to specify delta like this

   1  new FX.Element(element).animate({left: "+=100px"}).play();

“Cloneable”

One great feature is to be able to create an effect without specifying an element. Consider that like just specifying effect parameters. To be able to play it on a element, just clone the effect and call play.

This is very usefull for UI widget for instance. UI is usually created dynamically. In this case it’s pretty hard to give an effect as UI option because you do not know the element to apply the effect when you create your UI component.

With ProtoFX, you can have an effect parameter on your widget. The widget will clone it when it needs to play animation.

   1  var fx = new FX.Element().animate({opacity: 0});
   2  ...
   3  ...
   4  fx.cloneFor(element1).play();
   5  fx.cloneFor(element2).reverse().play();

Event notifications and callbacks

As a lot of prototype add-ons, ProtoFX fire events on different actions like ‘fx:started”, “fx:stopped” ... You just need to observe those events if need be, as usual.

But sometimes, I think it needs too much code for simple action, so event notifications are also notify to callbacks. So you can write code like that:

   1  var fx = new FX.Element(element)
   2    .onBeforeStarted(function() {element.show();})
   3    .animate({height: '+=100px'})
   4    .play();

Instead of

   1  var fx = new FX.Element(element)
   2    .animate({height: '+=100px'})
   3    .play();
   4  
   5  
   6  document.observe('fx:beforeStarted', function(event) {
   7    event.element().show();
   8  }  
   9  
  10  // And do not forget to unregister the event!!
  11  

Element methods

I have also added some usefull element methods that I use a lot with scripty like Element#fade/appear, Element#blindUp/blindDown. I will add more if needed.

Based on Penner equations

Effect transitions are based on the famous Penner equations (like jQuery). It gives nice and fluid effects like bouncing effects.

Score

As I said, the queue system is called Score. but Score is an effect itself (subclass of Fx.Base) so you can also call play/stop/reverse/rewind on it!!

You can add effect at the beginning, at the end, after a specific effect. You can add delay between effects, even negative delay for effect overlap.

   1  var group = new FX.Score('group1');
   2  group.add(fx1)
   3       .add(fx2, {delay: -1000, position: 'last'})
   4       .add(fx3, {delay: -1000, position: 'first'})
   5       .add(fx4, {delay: 1000, after: 'fx2'});

Samples

Some samples are included with the distrib on github. Check out this fun example. Play with the play/stop and reverse checkbox. click on it when animation is running!!

Get it!

ProtoFX is under MIT Licence like Prototype. You can get it from github here: http://github.com/xilinus/protofx/tree/master

Documentation is generated with pdoc from Tobie Langel. Just run: rake doc to generate it locally.

Unit tests are coming soon :)