Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 344 lines (260 sloc) 19.606 kb
1fe42e9 @phiggins42 no message
phiggins42 authored
1 #format dojo_rst
2
b1a0a41 @ccmitchellusa no message
ccmitchellusa authored
3 Animations and Effects with Dojo
4 ================================
1fe42e9 @phiggins42 no message
phiggins42 authored
5
b7fbdd3 no message
MarcusReimann authored
6 :Status: Draft
7 :Version: 1.0
8
9 .. contents::
10 :depth: 2
11
1fe42e9 @phiggins42 no message
phiggins42 authored
12 Dojo provides several layers of Animation helpers, starting with Base Dojo (dojo.js), and adding in levels of incremental additions through the module system. All Animations in Dojo revolve around a single class: dojo._Animation. The underscore denotes a private constructor, and is not meant to be created directly, but rather used as the underlying control mechanism for the flexible FX API Dojo provides.
13
faee125 formatting: subheaders
MarcusReimann authored
14
15 ===============================
1fe42e9 @phiggins42 no message
phiggins42 authored
16 Getting to know dojo._Animation
faee125 formatting: subheaders
MarcusReimann authored
17 ===============================
1fe42e9 @phiggins42 no message
phiggins42 authored
18
ad99756 @ccmitchellusa no message
ccmitchellusa authored
19 As mentioned, dojo._Animation is the foundation class for all Dojo animations. It provides several simple methods good for controlling your animation, such as `play`, `pause`, `stop`, and `gotoPercent`. The most simple method which is required of all animations is `play`:
1fe42e9 @phiggins42 no message
phiggins42 authored
20
21 .. code-block :: javascript
22 :linenos:
23
24 var animation = dojo.fadeOut({ // returns a dojo._Animation
acfbcab @ccmitchellusa no message
ccmitchellusa authored
25 // this is an Object containing properties used to define the animation
1fe42e9 @phiggins42 no message
phiggins42 authored
26 node:"aStringId"
27 });
28 // call play() on the returned _Animation instance:
29 animation.play();
30
fa8538b @ccmitchellusa no message
ccmitchellusa authored
31 You can simplify the above code using chaining, if you don't need to keep the animation object around for later use as follows:
1fe42e9 @phiggins42 no message
phiggins42 authored
32
33 .. code-block :: javascript
34 :linenos:
35
36 dojo.fadeOut({ node:"someId" }).play();
37
acfbcab @ccmitchellusa no message
ccmitchellusa authored
38 All animations in Dojo (with the exception of dojo.anim, introduced in Dojo 1.2) use predefined animation properties on the Object parameter to specify the animation settings. The `node:` property is the most important, and points to a node in the DOM on which to apply the animation. `node` can be a String ID of a DOM node, or a direct reference to a DOM node you already have:
1fe42e9 @phiggins42 no message
phiggins42 authored
39
40 .. code-block :: javascript
41 :linenos:
42
43 var target = dojo.byId("someId").parentNode;
44 dojo.fadeOut({ node: target }).play();
45
acfbcab @ccmitchellusa no message
ccmitchellusa authored
46 Animation Properties
47 --------------------
1fe42e9 @phiggins42 no message
phiggins42 authored
48
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
49 The standard set of properties for specifying animation settings (via the Object parameter to the animation function) are:
149a351 @ccmitchellusa no message
ccmitchellusa authored
50
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
51 +-------------------------------+--------------------------------------------------------------------------------------------+
5761d64 @phiggins42 no message
phiggins42 authored
52 |**Property** |**Description** |
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
53 +-------------------------------+--------------------------------------------------------------------------------------------+
9fb1455 @phiggins42 no message
phiggins42 authored
54 | node |The domNode reference or string id of a node to apply the animation effects to. |
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
55 | | |
56 | |**required** |
57 +-------------------------------+--------------------------------------------------------------------------------------------+
58 | delay |Delay, in milliseconds, before the animation starts. The default is 0ms. |
59 | | |
60 | |**optional** |
61 +-------------------------------+--------------------------------------------------------------------------------------------+
9fb1455 @phiggins42 no message
phiggins42 authored
62 | duration |How long, in milliseconds, the animation will run. The default is 350 milliseconds |
2c86744 @phiggins42 no message
phiggins42 authored
63 | |(.35 seconds) |
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
64 | | |
65 | |**optional** |
66 +-------------------------------+--------------------------------------------------------------------------------------------+
67 | easing |An easing (timing) function to apply to the effect, such as exponential curve, bounce, |
68 | |etc. Dojo provides a number of easing functions in module |
69 | |`dojo.fx.easing <dojo/fx/easing>`_ |
70 | | |
71 | |**optional** |
72 +-------------------------------+--------------------------------------------------------------------------------------------+
2c86744 @phiggins42 no message
phiggins42 authored
73 | rate |By default dojo runs its animations with 50 frames/second. This can be too fast in certain |
0007860 @ccmitchellusa no message
ccmitchellusa authored
74 | |scenarios when want the whole animation to run a lot slower. To change the framerate you use|
75 | |the rate property which defines the pause/delay between each frame. Ex. if you want 5 frames|
76 | |per second you should specify a rate of 200 (miliseconds between each frame) |
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
77 | | |
78 | |**optional** |
79 +-------------------------------+--------------------------------------------------------------------------------------------+
80 | repeat |How many times the animation will be played. Default: 0. |
81 | | |
82 | |**optional** |
83 +-------------------------------+--------------------------------------------------------------------------------------------+
7146123 @phiggins42 no message
phiggins42 authored
84 | curve |An array two values, or an instance of a `dojo._Line`. Used as the start and end points for |
85 | |a given animation. Typically not used directly by end-users, though allows usage of the |
86 | |Animation class outside of Node effects |
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
87 +-------------------------------+--------------------------------------------------------------------------------------------+
88
b3b68aa @ccmitchellusa no message
ccmitchellusa authored
89 Animation Events
90 ----------------
91
92 Performing custom behavior at specific points during an animation is done using callback functions (also set via the Object parameter to the animation function). These functions will be executed at various stages during an animation's life-cycle.
93
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
94 The standard set of events that are fired during stages of an animation are:
149a351 @ccmitchellusa no message
ccmitchellusa authored
95
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
96 +-------------------------------+--------------------------------------------------------------------------------------------+
97 +**Property** |**Description** |
98 +-------------------------------+--------------------------------------------------------------------------------------------+
99 | beforeBegin |A callback function which will be executed synchronously before playing the animation. |
100 | | |
cf2a76a @phiggins42 no message
phiggins42 authored
101 | |**optional** **new in 1.4**: passed node reference for the animation |
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
102 +-------------------------------+--------------------------------------------------------------------------------------------+
103 | onBegin |A callback function which will be executed asynchronously immediately after starting the |
104 | |animation. |
1b9cba2 @ccmitchellusa no message
ccmitchellusa authored
105 | | |
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
106 | |**optional** |
107 +-------------------------------+--------------------------------------------------------------------------------------------+
108 | onEnd |A callback function which will be executed synchronously when the animation ends. |
109 | | |
cf2a76a @phiggins42 no message
phiggins42 authored
110 | |**optional** **new in 1.4**: passed node reference for the animation |
ff5c1e4 @ccmitchellusa no message
ccmitchellusa authored
111 +-------------------------------+--------------------------------------------------------------------------------------------+
112 | onPlay |A callback function which will be executed synchronously when the animation is played. |
113 | | |
114 | |**optional** |
115 +-------------------------------+--------------------------------------------------------------------------------------------+
116 | onAnimate |A callback function fired for every step of the animation, passing |
117 | |a value from a dojo._Line for this animation. |
118 | | |
119 | |**optional** |
120 +-------------------------------+--------------------------------------------------------------------------------------------+
121
1fe42e9 @phiggins42 no message
phiggins42 authored
122 Consider this simple fade animation, and all the potential callbacks registered:
123
124 .. code-block :: javascript
125 :linenos:
126
127 dojo.fadeOut({
128
129 // some node, by id to animate:
130 node:"someId",
131
132 beforeBegin: function(){
133 // executed synchronously before playing
134 },
135 onBegin: function(){
136 // executed asynchronously immediately after starting
137 },
138 onEnd: function(){
139 // executed when the animation is done
140 },
141 onPlay: function(){
142 // executed when the animation is played
143 },
144 onAnimate: function(values){
145 // fired for every step of the animation, passing
146 // a value from a dojo._Line for this animation
147 }
148
149 }).play();
150
acfbcab @ccmitchellusa no message
ccmitchellusa authored
151 You can define these callback functions as part of the Object parameter used to define the animation initially (as seen above) or use `dojo.connect <dojo/connect>`_ to connect directly to the instance and listen for the function calls.
1fe42e9 @phiggins42 no message
phiggins42 authored
152
153 .. code-block :: javascript
0e31b7b @phiggins42 no message
phiggins42 authored
154 :linenos:
155
1fe42e9 @phiggins42 no message
phiggins42 authored
156 var animation = dojo.fadeOut({ node:"someNodebyId" });
157 dojo.connect(animation, "onEnd", function(){
158 // connect externally to this animation instance's onEnd function
159 });
160 animation.play(); // start it up
faee125 formatting: subheaders
MarcusReimann authored
161
b005536 @kylehayes fixed a typo
kylehayes authored
162 **new in Dojo 1.4** - The onEnd and beforeBegin events are fired passing a reference to the node being animated so that you may more easily manipulate a node immediately before or after an animation:
cf2a76a @phiggins42 no message
phiggins42 authored
163
164 .. code-block :: javascript
165 :linenos:
166
167 dojo.fadeOut({
168 node:"foo",
169 onEnd: function(n){
170 n.innerHTML = "";
171 },
172 beforeBegin: function(n){
173 n.innerHTML = "Bye!";
174 }
175 }).play();
176
faee125 formatting: subheaders
MarcusReimann authored
177
178 ===============
0e31b7b @phiggins42 no message
phiggins42 authored
179 Base Animations
faee125 formatting: subheaders
MarcusReimann authored
180 ===============
0e31b7b @phiggins42 no message
phiggins42 authored
181
acfbcab @ccmitchellusa no message
ccmitchellusa authored
182 Base Dojo provides the animation framework as well as several simple helper animations for fading, and one incredibly useful function `dojo.animateProperty` (the workhorse of most CSS-based animations). All use the same Object parameter format for specifying properties of the animation, and several additional options are used in advanced cases.
0e31b7b @phiggins42 no message
phiggins42 authored
183
184 Fading Example
faee125 formatting: subheaders
MarcusReimann authored
185 --------------
0e31b7b @phiggins42 no message
phiggins42 authored
186
187 To fade out a node, alter it's contents, and fade it back in:
188
189 .. code-block :: javascript
190 :linenos:
191
192 var node = dojo.byId("someId");
193 dojo.fadeOut({
194 node: node,
195 onEnd: function(){
196 node.innerHTML = "<p>Like magic!</p>"
197 dojo.fadeIn({
198 node: node
199 }).play()
200 }
201 }).play();
202
203 Here, we've created a fadeOut animation, and run it immediately. At the end of the animation (set here to use the default duration by omitting the `duration:` parameter), we set the node reference's `.innerHTML` property to something new, and fade it back in, again using the default duration.
204
1ada123 @ccmitchellusa no message
ccmitchellusa authored
205 Animating CSS Properties
206 ------------------------
0e31b7b @phiggins42 no message
phiggins42 authored
207
1ada123 @ccmitchellusa no message
ccmitchellusa authored
208 In addition to generic animations, Dojo provides shorthand helper functions for animating CSS properties via the `animateProperty <dojo/animateProperty>`_ API. An example where this specialized animation API simplifies specifying animation would be when you need to fade a background color property from red to green to indicate status changes.
faee125 formatting: subheaders
MarcusReimann authored
209
210 =================================
0e31b7b @phiggins42 no message
phiggins42 authored
211 Core Animations: Advanced helpers
faee125 formatting: subheaders
MarcusReimann authored
212 =================================
0e31b7b @phiggins42 no message
phiggins42 authored
213
214 Above the Base Animations (those contained entirely within dojo.js), there are several modules
215 available within the toolkit for advanced animation control.
216
217 To use these extended functions, you must include the `dojo.fx` module:
218
219 .. code-block :: javascript
220 :linenos:
221
222 dojo.require("dojo.fx");
223
224 The namespace `dojo.fx` has been reserved for all these animation, including `dojo.fx.chain` and `dojo.fx.combine`.
225
faee125 formatting: subheaders
MarcusReimann authored
226
227 =================================
0e31b7b @phiggins42 no message
phiggins42 authored
228 Chaining and Combining Animations
faee125 formatting: subheaders
MarcusReimann authored
229 =================================
0e31b7b @phiggins42 no message
phiggins42 authored
230
ad99756 @ccmitchellusa no message
ccmitchellusa authored
231 Two convenience functions provided in the `dojo.fx` module named `combine` and `chain` create an animation from a series of animations in an array.
0e31b7b @phiggins42 no message
phiggins42 authored
232
ad99756 @ccmitchellusa no message
ccmitchellusa authored
233 `combine` merges the array of animations them into one animation instance to control them all in parallel, whereas `chain` merges the animations into a single animation, playing back each of the animations in series, or one right after the other.
0e31b7b @phiggins42 no message
phiggins42 authored
234
235 To fade out two nodes simultaneously:
236
237 .. code-block :: javascript
238 :linenos:
239
240 dojo.require("dojo.fx");
241 dojo.addOnLoad(function(){
242 // create two animations
243 var anim1 = dojo.fadeOut({ node: "someId" });
244 var anim2 = dojo.fadeOut({ node: "someOtherId" });
245 // and play them at the same moment
246 dojo.fx.combine([anim1, anim2]).play();
247 });
248
acfbcab @ccmitchellusa no message
ccmitchellusa authored
249 (Notice we wrapped the animation call in and addOnLoad function this time. This is required always, as you cannot modify the DOM before the DOM is ready, which `addOnLoad <dojo/addOnLoad>`_ alerts us to. Also, we need to ensure the `dojo.fx` module has been loaded properly)
0e31b7b @phiggins42 no message
phiggins42 authored
250
acfbcab @ccmitchellusa no message
ccmitchellusa authored
251 Javascript is rather flexible about return values and where functions are called. The above example can alternatively be written in a shorthand like:
0e31b7b @phiggins42 no message
phiggins42 authored
252
253 .. code-block :: javascript
254 :linenos:
255
256 dojo.require("dojo.fx");
257 dojo.addOnLoad(function(){
258 // create and play two fade animations at the same moment
259 dojo.fx.combine([
260 dojo.fadeOut({ node: "someId" }),
261 dojo.fadeOut({ node: "someOtherId" })
262 ]).play();
263 });
264
ad99756 @ccmitchellusa no message
ccmitchellusa authored
265 The same rules apply to a combined animation as do a normal animation, though with no direct way to mix event callbacks into the combine() call, you are left using the `dojo.connect` method to attach event handlers:
0e31b7b @phiggins42 no message
phiggins42 authored
266
267 .. code-block :: javascript
268 :linenos:
269
270 var anim = dojo.fx.combine([
271 dojo.fadeOut({ node: "id", duration:1000 }),
272 dojo.fadeIn({ node: "otherId", duration:2000 })
273 ]);
274 dojo.connect(anim, "onEnd", function(){
275 // fired after the full 2000ms
276 });
277
acfbcab @ccmitchellusa no message
ccmitchellusa authored
278 Alternately, you can mix event handlers into your individual animations passed to dojo.fx.combine:
0e31b7b @phiggins42 no message
phiggins42 authored
279
280 .. code-block :: javascript
281 :linenos:
282
283 var animA = dojo.fadeOut({
284 node:"someNode",
285 duration: 500,
286 onEnd: function(){
287 // fired after 500ms
288 }
289 });
290 var animB = dojo.fadeIn({ node:"otherNode" });
291 dojo.fx.combine([animA, animB]).play();
292
293 Chain works in much the same way - though plays each animation one right after the other:
294
295 .. code-block :: javascript
296 :linenos:
297
298 dojo.fx.chain([
299 dojo.fadeIn({ node: "foo" }),
300 dojo.fadeIn({ node: "bar" })
301 ]).play();
302
ad99756 @ccmitchellusa no message
ccmitchellusa authored
303 All of the same patterns apply to chain as to other animation instances. A good article covering `advanced usage of combine and chain <http://dojocampus.org/content/2008/04/11/staggering-animations/>`_ is available at DojoCampus.
0e31b7b @phiggins42 no message
phiggins42 authored
304
305 combine and chain accept an Array, and will work on a one-element array. This is interesting because you can manually create animations, pushing each into the array, and chain or combine the resulting set of animations. This is useful when you need to conditionally exclude some Animations from being created:
306
307 .. code-block :: javascript
308 :linenos:
309
310 // create the array
311 var anims = [];
312 // simulated condition, an array of id's:
313 dojo.forEach(["one", "two", "three"], function(id){
314 if(id !== "two"){
315 // only animate id="one" and id="three"
316 anims.push(dojo.fadeOut({ node: id }));
317 }
318 });
319 // combine and play any available animations waiting
320 dojo.fx.combine(anims).play();
321
ad99756 @ccmitchellusa no message
ccmitchellusa authored
322 Obviously, any logic for determining if a node should participate in an animation sequence is in the realm of the developer, but the syntax should be clear. Create an empty Array, push whichever style and types of animations you want into the Array, and call combine() on the list.
0e31b7b @phiggins42 no message
phiggins42 authored
323
faee125 formatting: subheaders
MarcusReimann authored
324
325 ================
0e31b7b @phiggins42 no message
phiggins42 authored
326 Animation Easing
faee125 formatting: subheaders
MarcusReimann authored
327 ================
0e31b7b @phiggins42 no message
phiggins42 authored
328
25970ac @ccmitchellusa no message
ccmitchellusa authored
329 Have you ever wanted to perform an animated effect such as fade out, fade in, wipe in, but apply the effect in a non-linear way? For example, wouldn't it be cool to have a fade in accelerate the rate at which the node appears the further along in the animation duration it is, or provide a bit of bounce to your slide in animation? The functions which control the timing of the animation is handled through the 'easing' property of the arguments passed to the animation creation functions.
330
331 Instead of having to write the easing function yourself, dojo provides a collection of standard easing functions to use as this parameter to get a variety of effects. See `Easing functions <dojo/fx/easing>`_ for more information on the easing function provided out of the box.
332
333 ============
334 Text Effects
335 ============
336
337 As mentioned above, the dojox/fx module provides additional effects over and beyond these basic animation capabilities. On of the effects in the dojox package that is especially neat is effects that can operate on text directly, which can allow you to easily do animations such as exploding all the characters in a paragraph all over your page. Make sure to check out these additional text effects once you understand the basics.
07c7ac3 no message
santilli authored
338
339 =============================
340 Animation in Dojo 1.5 widgets
341 =============================
342
343 Using the latest in CSS3 along with the Dojo APIs increases the performance of animation and makes it easier for designers to code the animation using CSS3. See 'Themes and theming <http://docs.dojocampus.org/dijit-themes for more information>'_
Something went wrong with that request. Please try again.