Adding Entities

Custom Entities

A Clip's context normally consists of the elements defined in its HTML/CSS. But sometimes you need to add new elements dynamically at runtime — for example, spawning a new shape, adding a notification box, or introducing an element that wasn't part of the original template.

addCustomEntity is a method available on all Clips — both HTMLClip (provided by MotorCortex) and any Clip exposed by a plugin. Each Clip type implements its own internal mechanism for creating and rendering the entity within its context.

For plugin Clips, refer to the plugin's documentation for specifics on how entities are defined and rendered. Below we cover the HTMLClip implementation.

addCustomEntity on HTMLClip

On HTMLClip, addCustomEntity creates a new DOM element from an HTML string and appends it to the Clip's context so it can be targeted by Incidents.

• Method: addCustomEntity
• Arguments:

Argument	Type	Default	Description
definition	object	—	Describes the element to create. For HTMLClip: { html: "<div>...</div>" }
id	string	—	Unique identifier. Used in selectors as !#myEntity
classes	string[]	[]	Optional classes. Used in selectors as !.myClass
hidden	boolean	true	If true, the entity starts hidden (opacity: 0). Use CSSEffect to reveal it on the timeline
parentId	string	—	(optional) ID of an existing entity to nest this one inside

• Returns: boolean — true if the entity was created successfully.

HTMLClip definition format

For HTMLClip, the definition object requires a single key:

Key	Type	Description
html	string	The HTML markup of the element to create

The html string is parsed and the resulting element is appended to the Clip's root element (or to a parent entity if parentId is specified). SVG markup is also supported — if the target parent is an SVG element, the markup is parsed in the SVG namespace automatically.

Example

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

const clip = new HTMLClip({
  host: document.getElementById("app"),
  html: `<div class="scene"></div>`,
  css: `
    .scene {
      position: relative;
      width: 600px;
      height: 400px;
      background: #1a1a2e;
    }
  `,
  containerParams: { width: "600px", height: "400px" },
});

// Add a red box dynamically
clip.addCustomEntity(
  {
    html: `<div style="width:80px; height:80px; background:#f72585; position:absolute; top:160px; left:20px; border-radius:8px;"></div>`,
  },
  "red-box",       // id — targetable as !#red-box
  ["boxes"],       // classes — targetable as !.boxes
  true             // starts hidden (opacity: 0)
);

// Fade it in
clip.addIncident(
  new CSSEffect(
    { animatedAttrs: { opacity: 1 } },
    { selector: "!#red-box", duration: 500 }
  ),
  0
);

// Slide it across the scene
clip.addIncident(
  new CSSEffect(
    { animatedAttrs: { left: "500px" } },
    { selector: "!#red-box", duration: 2000, easing: "easeInOutQuad" }
  ),
  500
);

Selectors

Custom entities use the ! prefix in selectors:

Selector	Targets
!#red-box	The entity with id red-box
!.boxes	All entities with class boxes

These work with any Incident that accepts a selector: CSSEffect, plugin Effects, etc.