Timeline Construction

The web player turns animation data into parsed timeline data ready to be constructed for animation.

When using:

you'll receive a Spirit.Groups object containing the parsed animation timeline groups.

Spirit.Groups API

/**
 * Container element
 *
 * @type {HTMLElement|SVGElement}
 */
rootEl

/**
 * Add group data
 *
 * @param group {Spirit.Group}
 */
add(group: Spirit.Group);

/**
 * Remove group data
 *
 * @param group {Spirit.Group}
 */
remove(group: Spirit.Group);

/**
 * Construct all groups at once.
 *
 * @param resolve {boolean}
 * @returns {Array<gsap.Timeline>}
 */
construct(resolve = false);

/**
 * Get group by name
 *
 * @param name {string}
 * @returns {Spirit.Group}
 */
get(name: string): Spirit.Group;

// LIST

/**
 * The actual groups list
 *
 * @type {Array<Spirit.Group>}
 */
list: Array<Spirit.Group>;

/**
 * Get group at index
 *
 * @param index {number}
 * @returns {Spirit.Group}
 */
at(index: number): Spirit.Group;

/**
 * Clear all groups
 */
clear(): void;

/**
 * Iterate over groups
 *
 * @param cb {Function}
 */
each(cb: (group: Spirit.Group) => void): void;

You can access a single Spirit.Group using the following methods on the groups object:

groups.at(index), get a group at list index, groups.at(0)
groups.get(name), get a group by name, groups.get('logo')
groups.each(cb), iterate over all groups, groups.each(group => { ... })

Spirit.Group API

/**
 * The group timeline
 *
 * @type {gsap.timeline|null}
 */
timeline

/**
 * Internal list of timelines
 * for each element
 *
 * @type {List}
 */
timelines

/**
 * Playback speed
 *
 * Setting this value updates
 * the timeScale of the GSAP timeline
 *
 * @type {number}
 */
timeScale

/**
 * The total duration in seconds
 * Setting this value updates the duration
 * and timeScale of the GSAP timeline
 *
 * @type {number}
 */
duration

/**
 * Name of the group
 *
 * @type {string}
 */
name

/**
 * Get unresolved timelines
 *
 * @returns {Array<Spirit.Timeline>}
 */
unresolved

/**
 * Get resolved timelines
 *
 * @returns {Array<Spirit.Timeline>}
 */
resolved

/**
 * Kill GSAP timeline
 *
 * @type {() => void}
 */
reset()

/**
 * Resolve transformObjects for timelines
 * Updates accordingly:
 *   this.resolved
 *   this.unresolved
 *
 * @returns {Spirit.Group}
 */
resolve()

/**
* Convert to a readable and interchangeable
* javascript object
*
* @type    {Function}
* @returns {object}
*/
toObject()

/**
* Construct the GSAP timeline
*
* @type {Function}
*/
construct()

Example:

spirit.setup(gsap);

const groups = spirit.create({ ... }, container);
const timelines = spirit.each(group => group.construct());

Under the hood

When constructing a group group.construct(), this happens:

Clear previous timeline & tweens for elements
Clear GSAP cache for elements
Construct new timelines for elements
Returns the updated master timeline

Once a group is constructed you can use the GSAP Timeline API to control the animation.

Why constructing?

A single element can be used in multiple animation groups. You need to tell the web player which animation needs to be played. Generate a new GSAP timeline that can be played and controlled on demand.

Example:

index.html

<body>
  <div id="container">
    <h1 data-spirit-id="title">Title</h1>
  </div>

  <button id="btn-1">play animation 1</button>
  <button id="btn-2">play animation 2</button>

  ...
</body>

app.js

"animation.json" contains 2 animation groups both animating <h1 data-spirit-id="title">Title</h1>

import spirit from 'spiritjs';
import gsap from 'gsap';

const btn1 = document.getElementById('btn-1');
const btn2 = document.getElementById('btn-2');

spirit.setup(gsap);

spirit.loadAnimation({
  container: document.getElementById('container'),
  path: './animation.json'
}).then( ({ animation1, animation2 }) => {
  btn1.onclick = () => {
    animation1.construct().play();
  };
  btn2.onclick = () => {
    animation2.construct().play();
  };
});

Construct Event

On group construction the construct event is dispatched. Listen for construct events:

const group = spirit.groups.get('my-animation');

group.on('construct', timeline => {
  console.log('group is constructed => ', timeline);
});

group.construct();

Access

Initially, the group.timeline instance is null. Once the group is constructed, the GSAP timeline instance will be accessible via group.timeline.

Example:

console.log(group.timeline); // null

group.construct();

console.log(group.timeline); // gsap.timeline