Runtime Props

Each timeline instance contains a props instance. This is a collection of internal property data.

In most cases you won't need to reference this props instance directly. Using the spirit.create() or spirit.load() should cover most scenarios.

To illustrate, this is what props looks like:

{
  x: {
    '0s': 0,
    '2s': 100
  },
  y: {
    '0s': 0,
    '2s': 100
  },
  z: {
    '0s': 0,
    '2s': 100
  }
}

Get timeline.props

import { create } from 'spiritjs'

// create groups
const groups = create(data /* Spirit app copy clipboard */)

// get group
const group = groups.get('ghost')

// get first timeline
const timeline = group.timelines.at(0)

// get props
const props = timeline.props

Iterate

props.each(prop => {

})

Get prop by property name

props.get('x')

Mappings

Mappings are automatically populated to each prop and its keyframes. You can get and set custom mappings here. By default the this keyword is mapped to the timeline.transformObject (Element) itself.

This is how you can add custom mappings:

props.mappings = [
  ...props.mappings,                 // keep the `this` mapping
  { regex: /foo/, map: 123 },        // add foo mapping
  { regex: /bar/, map: window.bar }  // add bar mapping
]

In the desktop app, we can now use eval values with these mappings for this timeline object, for example:

window.bar = { width: 100 }

The calculated x value would be 223 (foo => 123 + bar.width => 100 = 223).

In most cases you won't need custom mappings, but it might be valuable for complex animations.

API

/**
* Mappings
* Getter/setter
*
* @type {Array}
*/
mappings

/**
* Get property by name
*
* @type    {Function}
* @param   {string} propName
* @returns {Prop}
*/
get(propName)

/**
* Add properties
*
* @type    {Function}
* @param   {object|Prop|Array} props
* @returns {*}
*/
add(props)

/**
* Remove properties
*
* @type    {Function}
* @param   {object|Prop|Array} props
* @returns {*}
*/
remove(props)

/**
* Does this collection contain a prop
*
* @type    {Function}
* @param   {string} propName
* @returns {boolean}
*/
haveProp(propName)

/**
* Convert to a readable and interchangeable javascript object
*
* @type    {Function}
* @param   {boolean} ignoreEval
* @returns {object}
*/
toObject(ignoreEval = false)

/**
* Destroy this collection of properties
*
* @type {Function}
*/
destroy()

Add properties

Property name needs to be unique, duplicates are not allowed. Example:

// existing props:
{
  x: { ... },
  y: { ... }
}

// try to add `x`:
add({
  x: { ... }
})

// throws duplicate error, x already exists

toObject(ignoreEval = false)

See Timeline.toObject()

Events

You can listen to the following events:

// listen for add / remove properties
props.on('add', () => {})
props.on('remove', () => {})

// listen for changes
props.on('change', () => {})

// listen for props list change
props.on('change:list', () => {})

// listen for property name change
props.on('change:name', () => {})

// listen for keyframes changes
props.on('keyframes', () => {})

// listen for keyframes list change
props.on('keyframes:list', () => {})

// listen for keyframe changes
props.on('keyframe', () => {})

// listen for keyframe time change
props.on('keyframe:time', () => {})

// listen for keyframe value change
props.on('keyframe:value', () => {})

// listen for keyframe ease change
props.on('keyframe:ease', () => {})

// listen for add / remove keyframes
props.on('add:keyframe', () => {})
props.on('remove:keyframe', () => {})

Linked list

Each property can access its previous and next property (properties are sorted by property name).

To illustrate, given existing props:

{
  x: { ... },
  y: { ... },
  z: { ... }
}

Cycle forward

let prop = props.get('x')

while (prop) {
  console.log(prop.name)
  prop = prop.next()
}

// outputs: x, y, z

Cycle backward

let prop = props.get('z')

while (prop) {
  console.log(prop.name)
  prop = prop.prev()
}

// outputs: z, y, x

Try it out in the browser. Copy and paste this in the javascript console https://spiritapp.io:

let prop = spirit.groups.get('ghost').timelines.at(0).props.at(0)

while (prop) {
  console.log(prop.name)
  prop = prop.next()
}

Work in progress!

More detailed documentation is coming soon

results matching ""

    No results matching ""