Namespace: AnimationUtils

Oracle® JavaScript Extension Toolkit (JET)
16.1.0
F92237-01

Since:
  • 2.1
Module:
  • ojanimation

QuickNav

Methods

Type Definitions

Other Topics

Description

Customizing and Disabling Animation

Default animations can be customized or disabled at several levels with varying degrees of control:
  1. For all JET components.
  2. For all instances of a JET component.

1. For all JET components

There are several theme variables that control the speed of animations in JET. Applications can change their values to speed up or slow down animations for all components, or to disable animations altogether by setting them to 0:

$animationDurationShort: .25s !default;
$animationDurationMedium: .4s !default;
$animationDurationLong: .5s !default;

Note that setting them to 0 does not make the actions that invoke animations synchronous. For example, opening a dialog is an asynchronous action. By setting the animation duration to 0 simply makes the dialog appear to open immediately. Events related to the dialog opening are still fired asynchronously, though with a much shorter delay.

2. For All Instances of a JET Component.

Default animations for JET components are defined by component-specific theme variables. Changing the values of the theme variables for a particular component will affect the default animations for all instances of that component.

Adding Busy State

Animations are asynchronous by nature. Sometimes applications may need to wait for an animation to end before proceeding with other operations. All the effect methods in AnimationUtils return promises that are resolved when the animations end.

In cases where applications use the oj.BusyContext class to track the busy state of components or pages, it is up to the callers of the effect methods to add busy state to the appropriate context, which may or may not be the context that contains the element being animated.

Examples


Add a busy state while an animation is in progress: 

// Context node is usually the animated element but can also be a node for any
// context that wants to wait for the animation to end.
var contextNode = element;
var busyContext = oj.Context.getContext(contextNode).getBusyContext();
var resolveFunc = busyContext.addBusyState({"description": "Animation in progress"});
AnimationUtils.slideOut(element).then(resolveFunc);


Usage

Typescript Import Format
//This namespace exports multiple static methods or members. To import 
import * as AnimationUtils from "ojs/ojanimation";

//Now you can access the methods as AnimationUtils.methodName and so on

For additional information visit:


Styling Classes

.oj-animation-backface
Used by the AnimationUtils.flipIn and AnimationUtils.flipOut methods when the flipTarget option is set to "children".

In this use case, the children of an element represent the two faces of a card. The child element that represents the back face must have the oj-animation-backface marker class.

Methods

(static) animateHero(element, options) : {Promise.<boolean>}

Animation effect method for animating a hero element from one location to another. A hero element is an element that appears to be shared between a source location and a destination location, even though there are separate source element and destination element.

The following steps are taken by this method:

  1. Create a temporary div that has a z-index higher than that of the source and destination elements.
  2. Clone the source element.
  3. Position the cloned element on the temporary div at the same position as the source element.
  4. Hide the source and destination elements.
  5. Animate the cloned element by translating and scaling its position and size towards the destination element.
  6. Show the destination element.
  7. Remove the temporary div together with the cloned element that is on it.
This method provides callback parameters that can be used to override some of the steps.
Parameters:
Name Type Description
element Element The source element for the hero animation.
options Object Options applicable to the specific animation effect.
Properties
Name Type Argument Description
toElementSelector string A CSS selector which specifies the destination element that occupies the location to animate to.
toElementWaitTime number <optional>
 The time in millisecond to wait for the destination element to become present in the DOM tree. The default is 5000, which is equal to 5 seconds. No animation occurs and the promise returned by this function will be rejected if the destination element is not present when toElementWaitTime expires.
createClonedElement function(AnimationUtils.HeroContext):Element <optional>
 An optional application-provided function that returns the element used in animation.

By default animateHero will clone the source element specified by the "fromElement" parameter. Application can override this by returning a different element.
hideFromAndToElements function(AnimationUtils.HeroContext):void <optional>
 An optional application-provided function that controls the visibility of the source and destination elements during animation.

By default animateHero will hide both the source element and destination element while animating the cloned element.
animateClonedElement function(AnimationUtils.HeroContext):Promise <optional>
 An optional application-provided function that animates the cloned element.

By default animateHero will move and scale the cloned element to the position and size of the destination element.
showToElement function(AnimationUtils.HeroContext):void <optional>
 An optional application-provided function that controls the visibility of the destination element after animation.

By default animateHero will show the destination element after animation ends.
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

(static) collapse(element, options) : {Promise.<boolean>}

Animaton effect method for collapsing a HTML element.

When using this method to hide an element, the element should not have any border or padding, because border and padding are visible even if the element's height is set to 0. The use of "box-sizing: border-box" style doesn't change this behavior. If the element needs border and padding, create a wrapper element around it and call this method on the wrapper element instead.

Parameters:
Name Type Argument Description
element Element the HTML element to animate
options Object <optional>
 Options applicable to the specific animation effect.
Properties
Name Type Argument Description
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
persist string <optional>
 Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none".
direction string <optional>
 direction to collapse. Valid values are "height", "width", or "both". Default is "height".
startMaxHeight string <optional>
 starting max-height value to collapse from. Default is natural element height.
endMaxHeight string <optional>
 ending max-height value to collapse to. Default is "0".
startMaxWidth string <optional>
 starting max-width value to collapse from. Default is natural element width.
endMaxWidth string <optional>
 starting max-width value to collapse to. Default is "0".
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

(static) expand(element, options) : {Promise.<boolean>}

Animaton effect method for expanding a HTML element.
Parameters:
Name Type Argument Description
element Element the HTML element to animate
options Object <optional>
 Options applicable to the specific animation effect.
Properties
Name Type Argument Description
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
persist string <optional>
 Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none".
direction string <optional>
 direction to expand. Valid values are "height", "width", or "both". Default is "height".
startMaxHeight string <optional>
 starting max-height value to expand from. Default is "0".
endMaxHeight string <optional>
 ending max-height value to expand to. Default is natural element height.
startMaxWidth string <optional>
 starting max-width value to expand from. Default is "0".
endMaxWidth string <optional>
 starting max-width value to expand to. Default is natural element width.
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

(static) fadeIn(element, options) : {Promise.<boolean>}

Animaton effect method for fading in a HTML element.
Parameters:
Name Type Argument Description
element Element the HTML element to animate
options Object <optional>
 Options applicable to the specific animation effect.
Properties
Name Type Argument Description
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
persist string <optional>
 Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none".
startOpacity number <optional>
 starting opacity. Default is 0.
endOpacity number <optional>
 ending opacity. Default is 1.
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

(static) fadeOut(element, options) : {Promise.<boolean>}

Animaton effect method for fading out a HTML element.
Parameters:
Name Type Argument Description
element Element the HTML element to animate
options Object <optional>
 Options applicable to the specific animation effect.
Properties
Name Type Argument Description
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
persist string <optional>
 Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none".
startOpacity number <optional>
 starting opacity. Default is 1.
endOpacity number <optional>
 ending opacity. Default is 0.
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

(static) flipIn(element, options) : {Promise.<boolean>}

Animaton effect method for rotating a HTML element into view.
Parameters:
Name Type Argument Description
element Element the HTML element to animate
options Object <optional>
 Options applicable to the specific animation effect.
Properties
Name Type Argument Description
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
persist string <optional>
 Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none".
axis string <optional>
 The axis of the rotation. Valid values are "x" and "y". Default is "y".
startAngle string <optional>
 The starting angle of the rotation. Refer to CSS rotate() transform for valid values. Default is "-180deg", which shows the back face of the element.
endAngle string <optional>
 The ending angle of the rotation. Refer to CSS rotate() transform for valid values. Default is "0deg", which shows the front face of the element.
backfaceVisibility string <optional>
 The visibility of the back face when facing the user. Valid values are "visible" and "hidden". If set to "visible", the back face shows a mirrored image of the front face. If set to "hidden", the back face is invisible. Default is "hidden".
perspective string <optional>
 The 3D perspective for the element. Default is "2000px". A smaller value makes the 3D effect more pronounced during rotation.
transformOrigin string <optional>
 The axis location for the rotation. Refer to CSS transform-origin for valid values. Default is "center".
flipTarget string <optional>
 The target for flipping. Valid values are "element" and "children". Default is "element".

Set to "element" to flip the element itself.

Set to "children" to flip the children of the element. This is used when the element is a card-like structure that has children to represent the front and back faces of a card. The child that represents the back face must have the "oj-animation-backface" marker class. Use this option instead of the "transform-style: preserve-3d" CSS style because some browsers do not support "transform-style". See the cookbook for a Card Flip example of using this option.
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

(static) flipOut(element, options) : {Promise.<boolean>}

Animaton effect method for rotating a HTML element out of view.
Parameters:
Name Type Argument Description
element Element the HTML element to animate
options Object <optional>
 Options applicable to the specific animation effect.
Properties
Name Type Argument Description
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
persist string <optional>
 Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none".
axis string <optional>
 The axis of the rotation. Valid values are "x" and "y". Default is "y".
startAngle string <optional>
 The starting angle of the rotation. Refer to CSS rotate() transform for valid values. Default is "0deg", which shows the front face of the element.
endAngle string <optional>
 The ending angle of the rotation. Refer to CSS rotate() transform for valid values. Default is "180deg", which shows the back face of the element.
backfaceVisibility string <optional>
 The visibility of the back face when facing the user. Valid values are "visible" and "hidden". If set to "visible", the back face shows a mirrored image of the front face. If set to "hidden", the back face is invisible. Default is "hidden".
perspective string <optional>
 The 3D perspective for the element. Default is "2000px". A smaller value makes the 3D effect more pronounced during rotation.
transformOrigin string <optional>
 The axis location for the rotation. Refer to CSS transform-origin for valid values. Default is "center".
flipTarget string <optional>
 The target for flipping. Valid values are "element" and "children". Default is "element".

Set to "element" to flip the element itself.

Set to "children" to flip the children of the element. This is used when the element is a card-like structure that has children to represent the front and back faces of a card. The child that represents the back face must have the "oj-animation-backface" marker class. Use this option instead of the "transform-style: preserve-3d" CSS style because some browsers do not support "transform-style". See the cookbook for a Card Flip example of using this option.
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

(static) ripple(element, options) : {Promise.<boolean>}

Animaton effect method for rippling a HTML element.
Parameters:
Name Type Argument Description
element Element the HTML element to animate
options Object <optional>
 Options applicable to the specific animation effect.
Properties
Name Type Argument Description
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
offsetX string <optional>
 Horizontal offset of the ripple center, with a unit of either "px" or "%". If the unit is "px", it specifies the offset in pixels. If the unit is "%", it specifies the offset as a percentage of the element's width.
offsetY string <optional>
 Vertical offset of the ripple center, with a unit of either "px" or "%". If the unit is "px", it specifies the offset in pixels. If the unit is "%", it specifies the offset as a percentage of the element's height.
color string <optional>
 Color of the ripple. Default is specified in the "oj-animation-effect-ripple" CSS class.
diameter string <optional>
 Diameter of the ripple, with a unit of either "px" or "%". If the unit is "px", it specifies the diameter in pixels. If the unit is "%", it specifies the diameter as a percentage of either the element's width or height, whichever is less. Default is specified in the "oj-animation-effect-ripple" CSS class.
startOpacity number <optional>
 start opacity of the ripple. Default is specified in the "oj-animation-effect-ripple" CSS class.
endOpacity number <optional>
 end opacity of the ripple. Default is 0.
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

(static) slideIn(element, options) : {Promise.<boolean>}

Animaton effect method for sliding in a HTML element.
Parameters:
Name Type Argument Description
element Element the HTML element to animate
options Object <optional>
 Options applicable to the specific animation effect.
Properties
Name Type Argument Description
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
persist string <optional>
 Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none".
direction string <optional>
 Direction of the slide. Valid values are "left", "top", "right", "bottom", "start", and "end". Default is "start". This option is ignored if either offsetX or offsetY is specified.
offsetX string <optional>
 The offset on the x-axis to translate from. This value must be a number followed by a unit such as "px", "em", etc. If moving in a horizontal direction, default to element width. Otherwise, default to "0px".
offsetY string <optional>
 The offset on the y-axis to translate from. This value must be a number followed by a unit such as "px", "em", etc. If moving in a vertical direction, default to element height. Otherwise, default to "0px".
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

(static) slideOut(element, options) : {Promise.<boolean>}

Animaton effect method for sliding out a HTML element.
Parameters:
Name Type Argument Description
element Element the HTML element to animate
options Object <optional>
 Options applicable to the specific animation effect.
Properties
Name Type Argument Description
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
persist string <optional>
 Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none".
direction string <optional>
 Direction of the slide. Valid values are "left", "top", "right", "bottom", "start", and "end". Default is "start". This option is ignored if either offsetX or offsetY is specified.
offsetX string <optional>
 The offset on the x-axis to translate to. This value must be a number followed by a unit such as "px", "em", etc. If moving in a horizontal direction, default to element width. Otherwise, default to "0px".
offsetY string <optional>
 The offset on the y-axis to translate to. This value must be a number followed by a unit such as "px", "em", etc. If moving in a vertical direction, default to element height. Otherwise, default to "0px".
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

(static) zoomIn(element, options) : {Promise.<boolean>}

Animaton effect method for zooming in a HTML element.
Parameters:
Name Type Argument Description
element Element the HTML element to animate
options Object <optional>
 Options applicable to the specific animation effect.
Properties
Name Type Argument Description
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
persist string <optional>
 Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none".
axis string <optional>
 the axis along which to scale the element. Valid values are "x", "y", or "both". Default is "both".
transformOrigin string <optional>
 set the CSS transform-origin property, which controls the anchor point for the zoom. Default is "center".
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

(static) zoomOut(element, options) : {Promise.<boolean>}

Animaton effect method for zooming out a HTML element.
Parameters:
Name Type Argument Description
element Element the HTML element to animate
options Object <optional>
 Options applicable to the specific animation effect.
Properties
Name Type Argument Description
delay string <optional>
 The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s".
duration string <optional>
 The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms".
timingFunction string <optional>
 One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease".
persist string <optional>
 Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none".
axis string <optional>
 the axis along which to scale the element. Valid values are "x", "y", or "both". Default is "both".
transformOrigin string <optional>
 set the CSS transform-origin property, which controls the anchor point for the zoom. Default is "center".
Returns:

a promise that will be resolved when the animation ends

Type
Promise.<boolean>

Type Definitions

AnimationMethods

All the available animation methods supported in AnimationUtils
Supported Values:
Value
collapse
expand
fadeIn
fadeOut
flipIn
flipOut
ripple
slideIn
slideOut
zoomIn
zoomOut

HeroContext

The context object passed to callback functions in the animateHero method
Properties:
Name Type Description
clonedElement Element | null The cloned element. This property is null when createClonedElement is called. It will be the value returned by createClonedElement in other callback functions.
fromElement Element The source element
scaleX number The horizontal size ratio of the toElement to the fromElement
scaleY number The vertical size ratio of the toElement to the fromElement
toElement Element The destination element
toElementElapsedTime number The elapsed time in millisecond that the destination element becomes present in the DOM tree after animateHero is called. If desired, applications can use this information to adjust the animation. For example, if the destination element takes a long time to appear, a shorter animation may be used.
translateX number The x offset of the toElement from the fromElement
translateY number The y offset of the toElement from the fromElement