JSB: behavior.animate()

animate()

Animates the style properties of an element.

Syntax

behavior.animate(element, transitions);

The transitions argument is a JavaScript object literal that describes the style properties and how to animate them.

Each transition is a key/value pair where the key is the name of the style property and the value is a JavaScript object literal that describes the transition in detail.

This is the expanded syntax:

behavior.animate(element, {
  propertyName1: {
    start: "value",
    end: "value",
    delay: value, // seconds
    duration: value, // seconds
    timing: "nameOfTimingFunction" || timingFunction
  },
  
  propertyName2: transition2,
  
  ...,
  
  propertyNameN: transitionN
});

Transition Properties

start (optional)

Defaults to the initial computed value of the property being animated.

end

You need to specify this value. For length properties you may use measurement units other than pixels.

You should always state the measurement unit for length properties.

delay (optional)

The period to wait before beginning the transition. The default value is 0 (seconds).

duration (optional)

The length of the transition in seconds. The default value is 1 (second).

timing (optional)

The name of the timing function or a function object that can be used to calculate the current value.

Valid names are: "ease" (the default), "linear", "ease-in", "ease-out" and "ease-in-out".

If you supply a JavaScript function to calculate the current value then the function will receive four arguments:

t: The elapsed time in milliseconds.
b: The numeric start value.
c: The delta value (difference between start and end values).
d: The duration of the transition in milliseconds.

The first transition in a list of transitions defines the default values for delay, duration and timing.

All transition properties except end are optional. Because of this, you can just use a string to describe the transition if only the end point needs to be specfied.

For example:

behavior.animate(element, {
  color: {
    end: "red",
    duration: 2,
    timing: "linear"
  },
  
  backgroundColor:  {
    end: "white",
    duration: 2,
    timing: "linear"
  }
});

Is equivalent to:

behavior.animate(element, {
  color: {
    end: "red",
    duration: 2,
    timing: "linear"
  },
  
  backgroundColor: "white"
});

In the above example, the duration and timing properties are inherited from the first transition.

Example

Hover to start the animation.

Show code.

new jsb.Rule("#example", {
  onmouseenter: function(element) {
    this.animate(element, {
      width: {
        end: "600px",
        duration: 3
      },
      backgroundColor: "blue",
      borderColor: "orange"
    });
  },

  onmouseleave: function(element) {
    this.animate(element, {
      width: {
        end: "100px",
        duration: 0.5
      },
      backgroundColor: "red",
      borderColor: "green"
    });
  }
});

Notes

Competing transitions

All transitions are stored in an animation queue. The queue only allows one transition per style property of an element. That means that you cannot have two competing transitions for the same property.

If a competing transition is introduced into the queue then it is merged with the current transition according to the following rules:

The current transition always defines the timing function.
The newest transition determines the relative duration of the transition.
If the new transition’s end point is the same as the current transition’s start point then the current transition is reversed.

The reality of this is that you usually don't need to maintain animations yourself. If a transition is reversed (e.g. a hover state) then the animation queue will notice and smoothly reverse the transition for you.

Shorthand property names

You can use shorthand style names to describe a transition. If you use a shorthand name then it is expanded to generate several transitions.

The following transition:

behavior.animate(element, {
  borderTop: "2px solid red"
});

Is expanded to:

behavior.animate(element, {
  borderTopWidth: "2px",
  borderTopStyle: "solid",
  borderTopColor: "red"
});

You cannot specify transitions for the background and font shorthand properties.

JSB: JavaScript Behaviors