Custom Entities

There are cases that just HTML and CSS are not enough to serve your Clip's needs. Cases such as Clips that use webGL or canvas or Clips that use libraries that create entities that (in general) are not represented as DOM elements and thus the plain CSS selectors provided by MC can not target the entities that we want to animate.

In such cases the developer needs to extend the DOMClip and create new types of Clips that on initialisation they render custom entities and keep them on their context so they can later access them via selectors and perform animations on them.

For example let's suppose that we want to create a Clip that it takes as attributes a number of circles and rectangles and renders them on a canvas. In order to do so, after the Clip renders on the provided host as normal, it should create a canvas and programmatically draw the rectangles and the circles in it.

Example:

const MotorCortex = require("@kissmybutton/motorcortex");
class MyCustomClip extends MotorCortex.API.DOMClip {
afterRender(){
// create a canvas
const ctx = this.context.document.createElement('canvas');
// draw all rects and circles in it
...
// keep each of the rects and circles as custom entities
this.setCustomEntity('myRect_1', myRectObject, ['class1', 'class2'];
// put the canvas on the Clip's DOM
this.context.rootElement.appendChild(ctx);
}
}

The setCustomEntity method of the Clip, which should only be executed on the afterRender method of it, puts any number of custom entities on the context and takes exactly three params:

  • id: the id of the entity
  • Entity: the entity itself
  • Classes (optional): an array of strings each of which represents the class (group) that this entity belongs to (used for selecting multiple custom entities at once exactly as we can do with CSS selectors and classes via the ".<class>" string

Once we've created our custom entities we can apply any Incident on them.

In order to select a custom entity (and not a DOM element as supported by default by Clips) we need to add the "!" character prior to our selection.

For example if we want to target the custom entity with id: "myEntity" we should use the selector "!#myEntity" and if we want to target / select all custom entities belonging to class "class1" the selector "!.class1".

In order to expose custom Clips on plugins we should put it, instead of the regular incidents array, on the "Clip" keyword of our main.js file:

const MyCustomClip = require("./src/MyCustomClip");
module.exports = {
npm_name: "my-plugin-name",
Clip: MyCustomClip
};