A framework for quickly and structured create HTML5 animations with both HTML elements and video.
npm install @adapt-retail/animation-frameworkThe core concept of this animation framework is to help you create fast,
structured and logical animations using the GSAP animation framework.
We do this by helping you create sections/modules of your code, and then sowing it together on a higher level.
These modules are Timeline, Scene and Transition.
In your project folder run following code.
``bash`
npm install @adapt-retail/animation-framework
GreenSock GSAP is a animation standard for web, and we recommend you to read Get started guide to use GreenSock/GSAP in other projects to.
Timeline is the core class of this package. At this point every other class uses Timeline.
The Timeline class is extending from GSAP/TimelineMax.
Most of the time you will only use the Timeline class as the main timeline for
all other classes that inherits from the timeline class. Often you will find yourself using
the timeline through either a Scene or Transition.
`js
/**
* Import Timeline
*/
const Timeline = require('@adapt-retail/animation-framework');
// const { Timeline } = require('@adapt-retail/animation-framework'); // Also available
/**
* Import your scene, as we discuss in the Scene section
*/
const MyIntroScene = require( './Path/To/MyIntroScene' );
const MyScene = require( './Path/To/MyScene' );
/**
* Create the main timeline.
* We recommend you to add it to the window to access it from the console later
* as timeline.
*
* We all properties added to Timeline constructor will be added to TimelineMax
*/
window.timeline = new Timeline();
/**
* Add the Scene to the timeline.
* It will automaticly be rendered and added
* Make sure you new opp your Scene class
*
* You can allso pass data to your scene through the constructorj:w
*/
timeline.add( new MyIntroScene() );
timeline.add( new MyScene() );
/**
* The main timeline has to be kickstarted by running timeline.start() function.
* It will run the start function automaticly on every child Timline
*/
timeline.start();
`
> Quick tip: Each module handle its own logic.
> If you just want to work with MyScene, you can just comment out the
> MyIntroScene, and then you only see your MyScene logic and animations.
Cause of the Timeline is extended from TimelineMax you can also add logic like this:
`js`
timeline.from( element, 3, {
opacity: 0,
} );
#### The Timeline is not instant as TimelineMax
One change we made to the Timeline is that it does not execute at once all the
properties are added to it. This is to make it possible to wait for resources
to load and alter the timeline length without the TimelineMax skipping it.
Each parent timeline will wait for every child to notify when it is done. Then it
will notify its parent that it is done. This process will bubble up until its
main timeline, then it will add All into TimelineMax and run.
An example of a resource it to wait for a video to load to get it length.
You cannot alter the timelines duration after it is added to another timeline in
GSAP.
A result of this is that functions like totalDuration()
on a timeline before it has started, will not work.
You can overwrite this behaviour by adding following to constructor
`js`
window.timeline = new Timeline({
paused: false,
});
In this framework you will use the most of your time in a Scene.
The Scene is extending from Timeline that also inherits from TimelineMax.
You should think of each Scene as a Scene in a movie, or a section/module of
your animation. Try make your Scenes solve one task. Also remember Scenes can
add multiple sub Scenes. See example here.
#### Example class
`js
import {Scene} from '@adapt-retail/animation-framework';
class MyScene extends Scene {
constructor() {
super();
this.helloTo = 'world';
}
/**
* Return html string
*
* @return string
*/
template() {
return
;
} /**
* Animate the elemnts around.
* this.template references the first element in template function
*
* @return void
*/
animate() {
this.from( this.template, 5, {
x: '100%',
} );
this.from( this.template.querySelector( '.hello-to' ), .8, {
opacity: 0,
}, 0 );
}
}
`js
render() {
return {{{ description }}}
}
> Note: A template can only have one root HTML element, if multiple is set we will use
> the first one.
The template function is where you will add your HTML for this Scene. We are
using mustache to render variables to the template.
As a default you can access all
variables through the template.
##### Render to
As a default we are rendering each Scene and element to the document.body.
You can define what element you want to render your elements to like this:
`js
timeline.add( new Scene({
renderTo: document.querySelector( '.content' ),
}) );
`js
animate() {
/**
* Introduction movement for elemnt in template.
*/
this.to( this.template.querySelector( '.title' ), 1, {
ease: SlowMo.ease.config(0.1, 2, true),
scale: 1.5,
} ); /**
* Show the description half a second before the title movement is done.
*/
this.from( this.template.querySelector( '.description' ), .8, {
opacity: 0,
}, '-=.5' );
}
`The animate function is where you make all your elements move.
The animate will run when everything is rendered to the page.
As the scene is inheriting from TimelineMax, we are accessing the TimelineMax,
from using the
keyword. From there you can do everything a
TimelineMax can do.`js
setup() {
return new Promise( function( resolve, reject ) {
window.setTimeout( function() {
resolve();
}, 500 );
} );
}
`If you need to setup something or wait for resources to load before running
animation you can setup a
function in the class.The setup command returns a promise. This is to make timeline wait to sew the
full timeline together before each Scene, Transition and Timeline is done loading before rendering and running animation.
You can read about why here.
##### Before and after setup function hooks
None of the
beforeSetup() or afterSetup() need to return anything.The
beforeSetup() will run immediately before the setup() is executed.
The afterSetup() will run immediately after the setup() is executed.$3
`js
const { Transition } = require( '@adapt-retail/animation-framework' );timeline.add( new IntroScene );
timeline.add( new Transition ); // <-- Transition between Scenes
timeline.add( new ContentSectionScene );
timeline.add( new Transition ); // <-- Transition between Scenes
timeline.add( new OutroScene );
`The transition is extending from Scene and therefor inherits from Timeline and TimelineMax also.
You should also extend the Transition or use it as it is. Do not run functions
from it.
Transitions are the glue between Scenes, and you can look at as a
special Scene that handle the transition between two Scenes.
The framework notifies the Transitions about the Scene that should be animated
in (
) and what Scene should be animated out (this.out).The Core Transition class
is probably the best code reference about how to create a new version of it.
But here is an example:
`js
import {Transition} from '@adapt-retail/animation-framework';export default class SlideInOut extends Transition {
/**
* Animate the transition between two elements
* The this.to and this.from is automaticly set in the Timlineline
*
* this.to represents the element we are animating in
* this.from represents the element we are animating out
*
* @return void
*/
animate() {
// Animate the element out
if (this.out) {
this.to( this.out.template, this.transitionTime, {
x: '100%',
});
}
// Animate the element in
if (this.in) {
this.to( this.in.template, this.transitionTime, {
x: '-100%',
}, 0 );
}
}
}
`When your class is created you can use it like so:
js
const SlideInOut = require( './path/to/SlideInOut' );timeline.add( new FirstScene );
timeline.add( new SlideInOut ); // <-- Slides scenes from left to right
timeline.add( new SecondScene );
`$3
The video is under development, but can be reached by
js
const {Video} = require( '@adapt-retail/animation-framework' );
``See Video.js to see how it works.
This framework is built using the GSAP animation framework, and they are subject to their own license.
Read their license to make sure you are on the safe side on how you use this framework.
The code provided in this framework is available for usage by all clients of Adapt Retail.