Namespace: AnimationUtils

Oracle® JavaScript Extension Toolkit (JET)
5.2.0
E97691-01

QuickNav

Methods

Type Definitions

AnimationUtils

Version:
  • 5.2.0
Since:
  • 2.1
Module:
  • ojanimation
Utility methods for animating elements.

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.
  3. For one instance 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. These theme variables are listed in the API documentation for the ojAnimateStart event of each component.

3. For One Instance of a JET Component

Applications can customize animations triggered by actions in some components by listening for ojAnimateStart/ojAnimateEnd events and override action specific animations. See the documentation of individual components for support details of ojAnimateStart/ojAnimateEnd events and the associated actions.

To customize an animation, applications first listen to ojAnimateStart event and cancel the default animation. Then specify the new animation in one of several ways:

  • Call one of the animation effect methods in oj.AnimationUtils.
  • Call a 3rd-party animation function with a Javascript API, such as jQuery, GreenSock, Velocity.js, etc.
  • Define action-specific CSS style classes on the animated item. When an action triggers animation, a marker class of the form "oj-animate-<action>" (e.g. "oj-animate-open") is added to the animated element. After a slight delay, a second marker class of the form "oj-animate-<action>-active" (e.g. "oj-animate-open-active") is added. This allows application to define CSS transition on the element.

Examples


Disable a default "open" animation: 

myComponent.addEventListener( "ojAnimateStart", function( event ) {
  if (event.detail.action == "open") {
    event.preventDefault();
    event.detail.endCallback();
  }
});

Customize a default "open" animation with oj.AnimationUtils method: 

myComponent.addEventListener( "ojAnimateStart", function( event ) {
  if (event.detail.action == "open") {
    event.preventDefault();
    oj.AnimationUtils.slideIn(event.detail.element).then(event.detail.endCallback);
  }
});

Customize a default "close" animation with jQuery method: 

myComponent.addEventListener( "ojAnimateStart", function( event ) {
  if (event.detail.action == "close") {
    event.preventDefault();
    $(event.detail.element).fadeOut(event.detail.endCallback);
  }
});

Customize a default "update" animation with CSS style classes: 

// Cancel the default animation in the event listener
myComponent.addEventListener( "ojAnimateStart", function( event ) {
  if (event.detail.action == "update") {
    event.preventDefault();
    event.detail.endCallback();
  }
});



/* Define new animation in CSS
   Different selectors may be needed to target the CSS correctly */

/* State to animate from is marked by oj-animate-<action> class */ 
.selector .oj-animate-update {
  color: red;
}

/* State to animate to is marked by oj-animate-<action> and oj-animate-<action>-active classes */ 
.selector .oj-animate-update.oj-animate-update-active {
  transition: color 1s;
  color: black;
}

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 oj.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"});
oj.AnimationUtils.slideOut(element).then(resolveFunc);
Since:
  • 2.1

Methods

(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 oj.AnimationUtils
Supported Values:
Name Type
"collapse" string
"expand" string
"fadeIn" string
"fadeOut" string
"flipIn" string
"flipOut" string
"ripple" string
"slideIn" string
"slideOut" string
"zoomIn" string
"zoomOut" string