-
Notifications
You must be signed in to change notification settings - Fork 1
Home
Tradewind.js provides only one command, run
. To this command you should pass an array of instructions.
Each instruction
(element of the array of instructions) represent an animation.
This is the most basic instruction:
{
elements: /* [DOM string selector of elements] | jQuery collection */,
animations: [
{
property: "property1",
animationDetails: {
duration: "1s",
delay: "0.5s",
easing: "linear"
},
final: "[final value of the animation]"
}
]
}
- In elements you need to put one of the following:
- A simple DOM selector, like the ones used in jQuery. If for instance you want to apply the same animation to all the elements with class "red", you should set
elements: ".red"
. - A jQuery collection, if you want to run the animation specifically on those elements
- A simple DOM selector, like the ones used in jQuery. If for instance you want to apply the same animation to all the elements with class "red", you should set
- In animations you need to write an array of properties. Each element of this array must specify:
-
property: the property that you want to animate using CSS3 transitions, let's say "width": you'll write
property: "width"
-
animationDetails: duration, delay, easing (see the CSS3 specifications for these; in the CSS3 syntax
easing
corresponds totiming-function
) - final: the final value that you want the property to assume
-
property: the property that you want to animate using CSS3 transitions, let's say "width": you'll write
Let's make an example: I want the div with selector #ball
to change smoothly color to red, with a duration of 1 second. The call to tradewind.js will be:
tradeWind.run([
{
elements: "#ball",
animations: [
{
property: "background-color",
animationDetails: {
duration: "1s",
delay: "0s",
easing: "linear"
},
final: "red"
}
]
}
]);
In this basic call, you are passing an array containing only one instruction. This instruction applies to the elements matched by the selector "#ball" (thus, only one because it's a HTML id); the property to be animated is only one, "background-color"; the final value is "red".
You can specify an animation with a string shortcut of the following type:
"property final duration [delay] [easing]"
If you don't specify delay
and easing
, they will be set with the default values of 0s
and ease
.
Conversion of the previous example using the short form for animations
tradeWind.run([
{
elements: "#ball",
animations: [
"background-color red 1s 0s linear"
]
}
]);
Be careful about spaces when using the short form: tradeWind
splits the short form using spaces, so if you have to specify an rgb
value you have to be careful removing spaces:
tradeWind.run([
{
elements: "#ball",
animations: [
"background-color rgb(0, 0, 0) 1s 0s linear" // Doesn't work
"background-color rgb(0,0,0) 1s 0s linear" // Works
]
}
]);
You can pass a callback as the second parametern of run
. The callback will be executed when the last of the animatable properties has finished its transition.
tradeWind.run(instructions); // no callback
tradeWind.run(instructions, function () {
// here goes the callback
});
Callbacks are cross browser. Tradewind innerly calculates the overall timing, and uses setTimeout
to ensure that the callback is fired only once, in the exact end of the animations.
The following tradewind.js call
tradeWind.run([
{
elements: "#ball, #cube",
animations: [
{
property: "background-color",
animationDetails: {
duration: "1s",
delay: "0s",
easing: "linear"
},
final: "red"
}
]
}
]);
gets parsed into
#ball {
-webkit-transition-property: "background-color";
-moz-transition-property: "background-color";
-o-transition-property: "background-color";
transition-property: "background-color";
-webkit-transition-duration: "1s";
-moz-transition-duration: "1s";
-o-transition-duration: "1s";
transition-duration: "1s";
-webkit-transition-timing-function: "linear";
-moz-transition-timing-function: "linear";
-o-transition-timing-function: "linear";
transition-timing-function: "linear";
-webkit-transition-delay: "0s";
-moz-transition-delay: "0s";
-o-transition-delay: "0s";
transition-delay: "0s";
background-color: "red";
}
#cube {
-webkit-transition-property: "background-color";
-moz-transition-property: "background-color";
-o-transition-property: "background-color";
transition-property: "background-color";
-webkit-transition-duration: "1s";
-moz-transition-duration: "1s";
-o-transition-duration: "1s";
transition-duration: "1s";
-webkit-transition-timing-function: "linear";
-moz-transition-timing-function: "linear";
-o-transition-timing-function: "linear";
transition-timing-function: "linear";
-webkit-transition-delay: "0s";
-moz-transition-delay: "0s";
-o-transition-delay: "0s";
transition-delay: "0s";
background-color: "red";
}
As you can see, you save a lot of lines of code, and the overall animation is much more readable.
Moreover, all these styles are applied inline and completely removed after the animation is over. If you want to animate an object just once, why defining a permanent CSS style on it?
The three fields of animationDetails
are not compulsory. When not specified, each of those field will be compiled into its default value:
{
duration: "0s",
delay: "0s",
easing: "ease"
}
If you want you can use the three default values together, by just not defining animationDetails
.
For example, the following are all valid declarations of animations:
{
property: "width",
animationDetails: {
delay: "1.4s"
}
final: "30px"
}
is parsed into duration: "0s"
, delay: "1.4s"
, timingFunction: "ease"
.
{
property: "width",
animationDetails: {
duration: "1s",
easing: "linear"
}
final: "30px"
}
is parsed into duration: "1s"
, delay: "0s"
, timingFunction: "linear"
.
{
property: "width",
final: "30px"
}
is parsed into duration: "0s"
, delay: "0s"
, timingFunction: "ease"
.
Prestyles are an advanced feature of tradewind.js. In an instruction, you insert an array of prestyles if you want the animated object to have a chosen CSS style before the animation starts.
To insert an array of prestyles inside an instruction, you have to add it to the field called preStyling
.
{
elements: "#ball",
animations: [
...
],
preStyling: [
// prestyles go here!
]
}
An example of prestyles:
// Extended form
preStyling: [
{
property: "display",
value: "block"
},
{
property: "left",
value: "100%"
}
]
// Short form
preStyling: [
"display: block",
"left: 100%",
]
In this example, before the beginning of the animation, tradewind.js applies display:block; left:100%
to all the element matched by the selector in this instruction.
- To define recurrent animations in single page applications: for instance, if you want to let the user open a popup containing animated objects, then close it and open it again without reloading the page, prestyles will ensure you that the animation's initial conditions are always respected, no matter what your javascript did when the user closed the popup.
-
To animate objects that are not currently visible in the page: the best way to achieve this is defining a complete set of prestyles including
display:block
. If you don't do this you'll have a complicated life (and don't ever think about just settingopacity:0
, which has a high disruptive risk in complex pages).
Let's write an example that uses prestyling. In your web page, when the user clicks on a button, a colored circle will come down from the top of the page, then inflate and get progressively transparent until disappearing. You want this to happen in the same way every time the user clicks on the button.
I use the jQuery syntax to implement this example, but of course you can use whatever library you have in your project.
$("#button").bind("click", function () {
tradeWind.run([
{
elements: "#circle",
preStyling: [
{ // this is to make it appear
property: "display",
value: "block"
},
{ // the following prestyles
// are necessary to set the initial properties of the circle
property: "top",
value: "-100px"
},
{
property: "width",
value: "80px"
},
{
property: "height",
value: "80px"
},
{
property: "opacity",
value: "1"
}
],
animations: [
{
property: "top",
animationDetails: {
duration: "2s",
easing: "linear"
},
final: "200px"
},
{
property: "width",
animationDetails: {
duration: "1s",
delay: "2s"
},
final: "100%"
},
{
property: "height",
animationDetails: {
duration: "1s",
delay: "2s"
},
final: "100%"
},
{
property: "opacity",
animationDetails: {
duration: "1s",
delay: "2s"
},
final: "0"
}
]
}
], function () {
$("#circle").hide();
// I reset display:none in the callback,
// so I don't risk that this div will enter in conflict
// with the rest of the page
});
});
Of course, this animation is not perfect, because it changes only width
and height
without concurrently modifying top
and left
; but it's still a good example to learn from. Specificly, you should notice how I linked the second part of the animation to the first, using the delays.
The first part of the animation, in which the circle appears from the top of the page, has this timing:
duration: "2s"
delay: "0s" // this is implicit, because it takes the default value
while all the animations in the second part (properties width
, height
and opacity
) have the timing
duration: "1s"
delay: "2s"
This means that the second group of animations will start exactly when the first one finishes.
If you want to have consequent animations, the conjunction of delays described above is the best way to implement them, rather than putting them inside a callback (unless the animations represent logically separated things).
IE8 and IE9 don't support CSS3 transitions, on which tradewind.js is based: hence, the animations won't work. But, and this is the most useful thing of CSS3, even if an animation is not supported, the overall effect will be totally acceptable, because it's equivalent to a simple change of style.
Thus, you can safely use tradewind.js even supporting IE8 and IE9! If you do it, users with modern browsers will enjoy your animations, and users with IE8 and IE9 will see a simple change of style without errors being raised nor bad visual effects.
The only thing that is not automatically supported in IE8 and IE9 are tradewind.js callbacks, because they are fired after the calculated timing of your animations, and if the animations don't occur the user will still have to wait such a timing before the callback is fired.
Fortunately, in tradewind.js there is a mechanism that checks if you are using old browsers, in which case the callback is fired immediately without waiting for an animation that doesn't occur.
To use the IE8 / IE9 compatibility checker, just include Modernizr.js in your project: tradewind.js will automatically detect it, and if the value of the property "csstransitions" is "false", it will fire callbacks immediately.
Very, very simple! You don't even have to download the full version of Modernizr, the only important thing is that it has the property csstransitions
.
If you have to support IE8, remember to avoid opacity
!
tradewind.js uses always inline styles. So, if you have objects that already have CSS3 transition properties on them:
- those properties will be overwritten for the whole duration of tradewind.js execution
- when tradewind.js has finished working, the whole set of inline CSS3 transitions is removed, so if you change style of your object again, it will use again the transitions originally attached to it.
What does this mean? That with tradewind.js you don't have to worry about what your HTML objects do: you animate them safely, and when the animation is over they come back automatically to their original status.
A very nice example of the potential of tradewind.js is the following small demo: