jsAnimbeta

home

Welcome to the official website of the jsAnim javascript library. jsAnim was a clumbsy and poorly implemented library for adding mediocre animations to websites, sacrificing standards and accessibility. Weighing in at a whopping 25 kilobytes, jsAnim is a pretty bad idea.

I recommend you do not use this as-is, but there were still some good ideas, so I've moved the project to github.

downloads

Go to github

documentation

jsAnim is easy to include in your websites and easy to animate with. This guide should help developers use jsAnim.

the basics

To include the jsAnim library in your website, upload the jsAnim.js file to your web server and insert the following code into your html document. Make sure to change the path to jsAnim to match whatever directory you uploaded it to.



Animations are controlled via javascript. It would probably me useful to create a .js file for your animation functions, or simply integrate them into your current javascript code. To begin using jsAnim, you want to instantiate a jsAnimManager object. The jsAnimManager object controls the animation of several objects. You may want to instantiate more than one manager, depending on your needs, but for now, only one will be necessary.

var manager = new jsAnimManager(40);

The parameter for the jsAnimManager is the timestep-length in miliseconds. Using a value of 40 means that a frame will render every 40 milisecond. This parameter is optional, and will default to 40 if unspecified.

Almost any property of any element on the page can be animated, but first a jsAnimObject must be created.

var anim = manager.createAnimObject("elementId");

The element id is passed into the manager.createAnimObject() function and the animation object is returned. Animation objects can be used to manage a chain of animations for a sinlge element. Multiple managers can be created for a single object to animate more than one attribute at the same time. The syntax for animating a property is simple.

anim.add({property: Prop.top, from: 50, to: 500, duration: 2000});

This command would start the object with a top value of 50, and gradually change it to 500 over the course of 2 seconds.

Now that you have seen the basics of the jsAnim library, we can move on to exactly how everything is done.

jsAnimManager

As we mentioned above, the jsAnimManager object controls a set of animations. The jsAnimManager object is instantiated optionally with one parameter, the timestep. If no parameter is given, this value defaults to 20. Higher numbers result in choppier animation, but less resource use, while lower numbers result in smoother animations, but higher resource use.

Once instatiated, the jsAnimManager object has several accesible functions, as described below.

/*! 
	jsAnimManager object constructor
	Params:
		-[timestep] : time between frames, defaults to 40
*/
var manager = new jsAnimManager(timestep);

/*! 
	Called to create a new animation object
	Params:
		-objId : id of object being controlled
*/
var anim = manager.createAnimObject(objId);

/*! 
	Called to pause all managed animations
*/
manager.pause();

/*! 
	Called to unpause the animation manager
*/
manager.resume();

/*! 
	Called to set the appropriate style values to allow position to be
		controlled by jsAnim
	Params:
		-objId : id of object to be registered
		-[fixed] : fixed positioning, false to absolute fixed, defaults
			to false
*/
manager.registerPosition(objId, fixed);

All the fuunctions described above should be relatively easy to understand, with the exception of registerPosition(...), which will be covered in the next section.

jsAnim positioning

One of the poweful features of jsAnim is the advanced positioning system. Object's positions can be controlled by a variety of functions, but in order to begin using the positioning system, we should first understand jsAnim's coordinate system.

As shown, above, the jsAnim coordinate system is anchored at the top of the page, in the center. Positive x values represent a position to the right of the center, and negative values represent a position to the left. As the y value increases, the position moves further down the screen.

In order to take advantage of the positioning system, an object must be registered. This is accomplished by the jsAnimManager.registerPosition(...) function. Once registered, an object can then be used with the position animation properties (more on this later) and can also have its position set by calling element.setPosition(x,y). The position of an object is anchored at the object's center.

//Register the object for positioning
manager.registerPosition("object", false);

el = document.getElementById("object");

//Set the position of the object to (0,400)
el.setPosition(0, 400);

The second parameter of the registerPosition(...) function is whether or not you would like the position to be fixed, rather than absolute. If you pass the value true, the position will be fixed to the page, however if you do not specify the parameter or pass false, it will default to absolute.

simple animation

Animating is accomplished by creating a jsAnimObject by calling the jsAnimManager.createAnimObject(...) function. The jsAnimObject object has several accessible functions.

var anim = manager.createAnimObject(objId);

/*! 
	Called to add an animation to the chain
	Params:
		-params : a collection in the containing the following elements
			- property : the Prop object to animate
			- [from] : optional from value, if unspecified current
				value is used
			- to : the value to animate to
			- duration : the length of time this animation should take
			- [ease] : the jsAnimEase object to use, if unspecified 
				standard will be used
			- [loop] : the number of times to loop the animation, 
				negative values are infinite, if unspecified, 1 used
			- [onLoop] : the callback function for loop completion
			- [onComplete] : the callback function for animation
				completion
*/
anim.add({
	property: Prop.width,
	from: 50,
	to: 500,
	duration: 2000,
	ease: jsAnimEase.standard,
	loop: 2;
	onLoop: function() {alert('finished one loop')},
	onComplete function() {alert('done animating')}
});
	
/*! 
	Called to skip the current animation, can be used to exit an infinite
	loop
*/
anim.skip();

/*! 
	Called to pause this animator
*/
anim.pause();

/*! 
	Called to resume this animator
*/
anim.resume();

/*! 
	Called to kill this animator
*/
anim.kill();

The add method appends the animation commands to the end of the chain of animations. If the jsAnimObject is not currently involved in any animations, it will begin to run immediately. If it is, it will run this command once all others have been completed. To animate multiple properties simultaneously, you must have multiple jsAnimObjects attached to the same element.

Again, this is all fairly simple, and will become all the more clear when we finally see some examples. But for now, let's take a look at the available properties we have to animate.

Properties

The following is the list of properties available to animate, along with some notes about them.

//Delay the animation, only a duration parameter is needed
Prop.wait

//Position properties expect to and from values of the form
//new Pos(x, y)

//Position, following a line-based path
Prop.position

/*!
	Follows a semicircular path
	Params:
		-clockwise : True for clockwise, false otherwise
*/
Prop.positionSemicircle(clockwise)

/*! 
	Follows a circular path through target then back to start
	Params:
		-clockwise : True for clockwise, false otherwise
*/
Prop.positionCircle(clockwise)

//Position and margin properties should not be animated if 
//position is registered

Prop.top

Prop.right

Prop.bottom

Prop.left

Prop.margin

Prop.marginTop

Prop.marginRight

Prop.marginBottom

Prop.marginLeft

Prop.padding

Prop.paddingTop

Prop.paddingRight

Prop.paddingBottom

Prop.paddingLeft

//Border width properties require a from parameter

Prop.borderWidth

Prop.borderTopWidth

Prop.borderRightWidth

Prop.borderBottomWidth

Prop.borderLeftWidth

Prop.fontSize

//Height, width, and dimension attempt to preserve center 
//if position is registered

Prop.height

Prop.width

//Dimension to and from values should be of the form
//new Dim(height, width)

Prop.dimension

//Colour to and from values should be of the form
//new Col(red, green, blue) where parameters are a number
//between 0 and 255 inclusive

Prop.color

Prop.backgroundColor

Prop.borderColor 

//Opacity is between 0 and 1

Prop.opacity

easing

There are also several different types of easing that can be used to make animations look more natural. To get a better feel for how they all work, see the examples page.

Listed below are the easing types:

//Constant Rate
jsAnimEase.linear

//Starts slow, then speeds up
jsAnimEase.parabolicPos

//Starts fast, then slows down
jsAnimEase.parabolicNeg

/*!
	Overshoots target then returns to target
	Params:
		-g : overshoot amount [0-1]
*/
jsAnimEase.backout(g)


/*!
	Backs up a bit then moves to target
	Params:
		-g : backup amount [0-1]
*/
jsAnimEase.backin(g)

//Goes to target and then back at constant rate
jsAnimEase.bounceLinear

//Goes to target and then back at variable rate
jsAnimEase.bounceParabolic

//Goes to target and then back smoothly
jsAnimEase.bounceSmooth

That about covers the documentation of the jsAnim library. If anything remains unclears, see the examples page or email Kevin.

examples

This page offers some simple examples, we will call the mushroom experiments. First, let us begin with the basic setup for the html page. Create a file index.html and a file main.js, in the head of the index.html file, add the following code:




Make sure to put something to animate in the index.html file. For our experiments, we will be using a png image of a mushroom, which will give an id of mushroom. If you want the animations to begin when the page loads, it might be beneficial to create a function named init() and add onload="init()" to the body tag of your page.

In our main.js file, we can now instantiate the jsAnimManager object, with the following basic code:

var manager = new jsAnimManager();

We can now consider a basic example. We will give the mushroom a relative positioning, and then animate the left parameter to make it move from the left to the right of the page.

shroom = document.getElementById("mushroom");

shroom.style.position = "relative";

var anim = manager.createAnimObject("mushroom");

anim.add({property: Prop.left, to: 500, duration: 2000});

Now let's take a look at the same example, but instead, let's use the jsAnim positioning system.

shroom = document.getElementById("mushroom");

manager.registerPosition("mushroom");

shroom.setPosition(-250,25);

var anim = manager.createAnimObject("mushroom");

anim.add({property: Prop.position, to: new Pos(250,25), 
	duration: 2000});

The real power of the positioning system is that we can animate both a vertical and horizontal component at the same time, without having two animation objects.

shroom = document.getElementById("mushroom");

manager.registerPosition("mushroom");

shroom.setPosition(-250,25);

var anim = manager.createAnimObject("mushroom");

anim.add({property: Prop.position, to: new Pos(250,100),
	duration: 2000});

We can also animate from one position to the next in some path other than a straight line!

shroom = document.getElementById("mushroom");

manager.registerPosition("mushroom");

shroom.setPosition(-250,25);

var anim = manager.createAnimObject("mushroom");

anim.add({property: Prop.positionSemicircle(false), 
	to: new Pos(250,25), duration: 2000});

Or, we can even use the neat circle feature. This allows the object to be animated in a complete circle, where the to point represents the far-end of the circle.

shroom = document.getElementById("mushroom");

manager.registerPosition("mushroom");

shroom.setPosition(0,25);

var anim = manager.createAnimObject("mushroom");

anim.add({property: Prop.positionCircle(true), to: new Pos(0,100),
	duration: 2000});

Of course, we can animate more than just position. For instance, we can animate colors.

var anim = manager.createAnimObject("colorDiv");

anim.add({property: Prop.backgroundColor, to: new Col(00,255,133),
	duration:2000});

Animations can also be chained, such that one immediately follows the other. Note that we can also use the wait property to pause a chain for a set amount of time!

shroom = document.getElementById("mushroom");

manager.registerPosition("mushroom");

shroom.setPosition(-250,25);

var anim = manager.createAnimObject("mushroom");

anim.add({property: Prop.position, to: new Pos(250,25),
	duration: 2000});
anim.add({property: Prop.wait, duration: 1000});
anim.add({property: Prop.position, to: new Pos(0,100),
	duration: 2000});

To animate more than one property at the same time, we must create more than one jsAnimObject.

shroom = document.getElementById("mushroom");

manager.registerPosition("mushroom");

shroom.setPosition(-250,75);

var anim1 = manager.createAnimObject("mushroom");
var anim2 = manager.createAnimObject("mushroom");

anim1.add({property: Prop.position, to: new Pos(250,75),
	duration: 2000});
anim2.add({property: Prop.dimension, to: new Dim(140,20),
	duration: 2000});

You can use the onComplete callback to trigger events when animations are done.

shroom = document.getElementById("mushroom");

manager.registerPosition("mushroom");

shroom.setPosition(-250,25);

var anim = manager.createAnimObject("mushroom");

anim.add({property: Prop.position, to: new Pos(250,25), 
	duration: 2000, onComplete: function() {alert("HEY!")}});

To make animations look really nice, easing is absolutely vital. There are several different types of easing, and the best way to explain them is to simply show them. So for this, example, the different buttons describe which easing method was used in code like the following:

shroom = document.getElementById("mushroom");

manager.registerPosition("mushroom");

shroom.setPosition(-200,25);

var anim = manager.createAnimObject("mushroom");

anim.add({property: Prop.position, to: new Pos(200,25),
	duration: 2000, ease: /*[EASE METHOD HERE]*/});

So there you have it; that's everything I have to say about my animation library. If you have anything to say, just email me.