Skip to main content

Effect

What is an Effect​

Effects are Incidents that animate the attributes' values of selected elements of the context.

All Effects take exactly two arguments on initialisation:

  • attributes
  • properties

Both attributes and properties are of type object.

Example​

The best example of an Effect is the CSSEffect Incident provided by MotorCortex. This Effect can animate the css properties of any element of the Clip context. You can define what you want to animate, in how many milliseconds, select the elements you want to apply the effect and add this Incident anywhere on the Clip's timeline.

Let's add some action on our Clip's timeline by adding a CSSEffect

import { HTMLClip, CSSEffect } from "@donkeyclip/motorcortex";

// Clip definition
const myClip = new HTMLClip({
    host: document.getElementById("app"),
    html: `
    <div class="container">
      <div class="circle circle-a"></div>
      <div class="circle circle-b"></div>
      <div class="circle circle-c"></div>
      <div class="text-container">{{ initParams.text }}</div>
    </div>
  `,
    css: `
    .container{
      position: relative;
      width: 600px;
      height: 400px;
      font-family: 'Ubuntu', sans-serif;
      text-align: center;
      text-shadow: 2px 2px 2px #444;
      background: whitesmoke;
    }

    .circle{
      transform: scale(0);
      opacity: 0.7;
      position: absolute;
      border-radius: 100%;
    }

    .circle-a{
      top: 2%;
      left: 15%;
      width: 390px;
      height: 390px;
      background: #f72585;
    }

    .circle-b{
      top: 18%;
      left: 8%;
      width: 320px;
      height: 320px;
      background: #7209b7;
    }

    .circle-c{
      top: 11%;
      right: 15%;
      width: 210px;
      height: 210px;
      background: #3a0ca3;
    }

    .text-container{
      transform: scale(0);
      position: absolute;
      top: 55%;
      left: 15%;
      color: whitesmoke;
      font-size: 26px;
    }
  `,
    fonts: [
        {
            type: "google-font",
            src:
                "https://fonts.googleapis.com/css2?family=Ubuntu:wght@500;700&display=swap"
        }
    ],
    containerParams: {
        width: "600px",
        height: "400px"
    },
    initParams: {
        text: "Hello MotorCortex!"
    }
});

// Effect Definition
const myEffect = new CSSEffect(
    {
        animatedAttrs: {
            transform: {
                scaleX: 1,
                scaleY: 1
            }
        }
    },
    {
        selector: ".container>div",
        duration: "@stagger(400, 800, 0, easeOutCubic)",
        delay: "@stagger(0, 600)",
        easing: "easeOutBounce"
    }
);

// Add Effect to Clip
myClip.addIncident(myEffect, 0);

// Play the Clip
myClip.play();

Result (codesandbox):​

API​

CSSEffect is an Effect but there are hundreds of other Effects provided by the plugins. All Effects have the exact same functionality (they animate selected element's attributes) and all of them share the exact same syntax. They all accept attributes (each one expects for its own attributes) and they all accept the exact same properties.

Attributes​

The attributes that an Effect expects vary from plugin to plugin and from Effect to Effect, depending on the action it executes/represents. Two things are common in all of them though: the animatedAttrs and the (optional) initialValues.

As mentioned, Effects animate the value of elements' attributes. The attributes that the Effect handles and changes are always included on the animatedAttrs key of its attributes. Each key's value represents the final value that the attribute will reach at the end of the Effect (target value).

As an example, by the use of CSSEffect, we animate the background and the fontSize of all elements of class ".my-class" to "#000000" and "45px" respectively:

const myEffect = new CSSEffect(
    {
        animatedAttrs: {
            background: "#000000",
            fontSize: "45px"
        }
    },
    {
        selector: ".my-class",
        duration: 1000
    }
);

The initialValues key (optionally) provides initialValues for the animatedAttrs of the Effect. If no initialValues is provided MotorCortex automatically detects the current value of the animatedAttr and keeps that as its initial value for the animation. Example:

const myEffect = new CSSEffect(
    {
        animatedAttrs: {
            background: "#000000",
            fontSize: "45px"
        },
        initialValues: {
            fontSize: "12px"
        }
    },
    {
        selector: ".my-class",
        duration: 1000
    }
);

On the provided example the initialValues key only defines the initial value of the fontSize as background is absent. In this case, when the animation starts, MotorCortex will use the 12px as the initial value of fontSize while it will automatically detect the current value of the background and keep this as the initial value.

Except the animatedAttrs and the initialValues an Effect might expect / accept other keys as well on its attributes. This strongly depends on the implementation of each Effect and thus developers should always consult the plugin's documentation for details.

Properties​

Unlike attributes, the properties object is standard and the same for all Effects and it supports the following keys:

  • selector: the selector that defines the elements that the Effect should be applied to
  • duration: the duration of the Effect in milliseconds
  • delay: (optional, defaults to 0) if provided add a delay before the Effect execution. Delay is provided in milliseconds
  • repeats: (optional, defaults to 1) if provided it repeats the execution of the Effect as many times as the provided integer
  • hiatus: (optional, defaults to 0) if provided it adds a hiatus after the Effect execution. Hiatus is provided in milliseconds
  • id: (bad practice for production, use just for debugging purposes). The id of the Effect
  • name: Optionally, each Effect can have a name that the user can give for easy reference
  • easing: (optional, defaults to ‘linear’) if provided it sets the easing of the Effect. The supported easings are:
    • 'linear',
    • 'easeInQuad',
    • 'easeOutQuad',
    • 'easeInOutQuad',
    • 'easeInCubic',
    • 'easeOutCubic',
    • 'easeInOutCubic',
    • 'easeInQuart',
    • 'easeOutQuart',
    • 'easeInOutQuart',
    • 'easeInQuint',
    • 'easeOutQuint',
    • 'easeInOutQuint',
    • 'easeInSine',
    • 'easeOutSine',
    • 'easeInOutSine',
    • 'easeInExpo',
    • 'easeOutExpo',
    • 'easeInOutExpo',
    • 'easeInCirc',
    • 'easeOutCirc',
    • 'easeInOutCirc',
    • 'easeInElastic',
    • 'easeOutElastic',
    • 'easeInOutElastic',
    • 'easeInBack',
    • 'easeOutBack',
    • 'easeInOutBack',
    • 'easeInBounce',
    • 'easeOutBounce',
    • 'easeInOutBounce'

These props are standard among all Effects of any plugin, they are handled directly from MotorCortex and no other key out of this list can enter the properties object.