Dojo in XPages – 14: Custom Animations

In the last post, we looked at the dojo code to perform pre-defined animations. In reality, those are wrappers for the actual animation function. In this post, I’ll show how to animate any DOM element property so you can create your own custom animations.

Dojo in XPages Series

Dojo in XPages — All Blog Posts

dojo.animateProperty()

The Fade In/Out methods animate opacity attribute, the Wipe In/Out methods animate the height attribute, and the Slide To method animates the top and left attributes of an element.

The built-in methods are handy, bu you can write these same animations yourself pretty simply as well. This is good news because you can also easily modify the behavior as needed.

The animateProperty() method allows you to do this. It is part of core dojo — you don’t need to load the dojo.fx module in order to use it.

Custom Animation Simple Action Source

In a previous post I showed the simple actions that are available to create Dojo animations in XPages.

The custom animation shown in that post changed the background color (from red to blue) and the height (from 100px to 200px) of a simple div on the page.

Here’s the code that the simple action generated:

function view__id1__id9_clientSide_onclick(thisEvent) {
  var _id=dojo.byId("myDiv");
  var _a1 = dojo.animateProperty({"node":_id,"properties": {"backgroundColor": {"start":"#FF0000","end":"#0000FF"},"height": {"start":"100","unit":"px","end":"200"}}});
  _a1.play();
}

Here’s how you could write that yourself to perform that same animation

dojo.animateProperty({
  "node":"myDiv",
  "properties": {
    "backgroundColor": {"start":"#FF0000","end":"#0000FF"},
    "height": {"start":"100","unit":"px","end":"200"}
  }
}).play();

Another Example — Changing the Wipe Direction

The built in methods (in dojo.fx) to wipeIn() and wipeOut() an element work by modifying the height of the element. If you’d like to create a horizontal wipe effect, you can animate the width property instead.

This will wipe it out horizontally:

dojo.animateProperty({
  "node":"myDiv",
  "properties": {
    "width":{"end":"0"}
  }
}).play();

This will wipe it back in horizontally:

dojo.animateProperty({
  "node":"myDiv",
  "properties": {
    "width":{"end":"200"}
  }
}).play();

Additional Animation Properties

In addition to the required animation attributes, you can also define a delay before starting the animation, the duration of the animation (default is 350 milliseconds) and an easing function to modify the effect. (We’ll come back to that in the next post.) You can also change the frame rate and a repeat property to play the animation more than once.

Animation Events

I’m not going to dig into it here, but there are 5 animation events to which you can attach handlers if you need to trigger another action:

• beforeBegin
• onBegin
• onEnd
• onPlay
• onAnimate

Combining Animation of Mulitple Elements

If you want to animate multiple elements concurrently, you can define the animations as objects and use the combine() method to run them together. Since this method is part of the dojo.fx module, you’ll need to include that module on the page.

For example, if I have two divs on my page (myDiv and myOtherDiv) and I want to make the first one smaller and the second one larger, I can define both of those animations and chain them together like this:

var div1Animation = dojo.animateProperty({
  "node":"myDiv",
  "properties": {
    "width":{"end":"50"}
  }
});

var div2Animation = dojo.animateProperty({
  "node":"myOtherDiv",
  "properties": {
    "width":{"end":"300"}
  }
});

dojo.fx.combine([div1Animation, div2Animation]).play();

The combine() method takes an array of animation objects.

Up Next

At this point, you’re armed to create your own custom animations! In the next post we’ll look at the built-in easing methods available to modify the timing of how the animations play out.