Merge pull request #4 from feat/load-data-argument

Add data argument to the load() method

Author: nytamin

CHANGELOG.md

@@ -15,3 +15,5 @@ The log below details the changes during development of this version:
 * 2025-04-23: Fix in JSON-schemas: Changed `main` property in Graphics manifest to be **mandatory**.
   (Before, it was defined as mandatory in the specification document, but not in the JSON-schemas.)
 * 2025-05-16: Add `renderRequirements` property to Graphics manifest
+* 2025-05-16: Add `data` argument to the `load` method.
+  Before, the `data`-payload was only sent using the `updateData()` method. Now it must be sent on `load()` as well.

v1-draft-0/examples/l3rd-name/graphic.mjs

@@ -23,6 +23,7 @@ class MyGraphic extends HTMLElement {
     // 2. Setup the DOM
     // 3. Initialize the GSAP timeline
 
+
     // Load the GSAP scripts ---------------------------------------------------
     const importsPromises = {
       gsap: import(import.meta.resolve("./lib/gsap-core.js")),
@@ -109,6 +110,13 @@ class MyGraphic extends HTMLElement {
       this.timeline.pause();
     } else throw new Error("Unsupported renderType: " + loadParams.renderType);
 
+    // Load initial data:
+    this.initialData = loadParams.data
+    await this._doAction("updateAction", {
+      data: this.initialData || {},
+      skipAnimation: true
+    });
+
     // When everything is loaded we can return:
     return;
   }
@@ -171,6 +179,12 @@ class MyGraphic extends HTMLElement {
 
     // Initial state:
 
+    // Load initial data:
+    await this._doAction("updateAction", {
+      data: this.initialData || {},
+      skipAnimation: true
+    });
+
     for (const event of (this.nonRealTimeState.schedule || [])) {
       const tweens = this._getActionAnimation(
         event.action.type,
@@ -247,24 +261,26 @@ class MyGraphic extends HTMLElement {
   _getUpdateAnimation(params) {
     const gsap = this.g.gsap;
 
-    this.displayState.data = params.data
+    this.displayState.data = params.data || {}
+
+    const speed = params.skipAnimation ? 0 : 1
 
     const showTitle = this.displayState.data.title
     const isPlaying = this.displayState.isPlaying
 
     return [
       gsap.to(this.elements.nameText, {
-        duration: 0.4,
-        text: params.data.name,
+        duration: speed * 0.4,
+        text: this.displayState.data.name,
       }),
       gsap.to(this.elements.nameText2, {
-        duration: 0.4,
-        text: params.data.title,
+        duration: speed * 0.4,
+        text: this.displayState.data.title,
       }),
       (
         isPlaying &&
           gsap.to(this.elements.container2, {
-            duration: 0.3,
+            duration: speed * 0.3,
             y: 0,
             opacity: showTitle ? 1 : 0,
             ease: "power2.out",
@@ -273,7 +289,7 @@ class MyGraphic extends HTMLElement {
       (
         isPlaying &&
         gsap.to(this.elements.container, {
-          duration: 0.3,
+          duration: speed * 0.3,
           borderBottomLeftRadius: showTitle ? "0" : "20px",
           ease: "power2.out",
         })
@@ -285,7 +301,7 @@ class MyGraphic extends HTMLElement {
 
     this.displayState.isPlaying = true
 
-    const showTitle = Boolean(this.displayState.data?.title)
+    const showTitle = Boolean(this.displayState.data.title)
 
 
     return [
@@ -297,10 +313,6 @@ class MyGraphic extends HTMLElement {
         ease: "power2.out",
       }),
 
-      gsap.to(this.elements.nameText, {
-        duration: 0.4,
-        // text: this._currentData.name,
-      }),
       gsap.to(this.elements.container2, {
         delay: 0.3,
         duration: 0.8,
@@ -311,7 +323,6 @@ class MyGraphic extends HTMLElement {
       gsap.to(this.elements.nameText2, {
         delay: 0.7,
         duration: 0.8,
-        // text: this._currentData.name,
       }),
       gsap.to(this.elements.logo, {
         duration: 0.5,
@@ -321,7 +332,6 @@ class MyGraphic extends HTMLElement {
         duration: 1.5,
         rotation: 360,
         scale: 1
-        // text: this._currentData.name,
       }),
     ];
   }

v1-draft-0/specification/docs/Specification.md

@@ -66,7 +66,7 @@ The manifest file is a JSON file containing metadata about the Graphic. It consi
 | customActions       | Action[]           |          |         | An array of `Action` objects. They correspond to the custom actions that can be invoked on the Graphic. See below for details about the fields inside an `Action`.    |
 | supportsRealTime    | boolean            |    X     |         | Indicates whether the Graphic supports real-time rendering.                                                                                                        |
 | supportsNonRealTime | boolean            |    X     |         | Indicates whether the Graphic supports non-real-time rendering. If true, the Graphic MUST implement the non-real-time functions `goToTime()` and `setActionsSchedule()`.                 |
-| schema              | object             |          |         | The JSON schema definition for the parameter of the `updateAction()` function. This schema can be seen as the (public) state model of the Graphic.                   |
+| schema              | object             |          |         | The JSON schema definition for the `data` argument to the `load()` and `updateAction()` methods. This schema can be seen as the (public) state model of the Graphic.                   |
 | stepCount           | integer            |          |    1    | The number of steps a Graphic consists of.                                                                                                                         |
 | renderRequirements  | RenderRequirement[]|          |         | A list of requirements that this Graphic has for the rendering environment. At least one of the requirements must be met for the graphic to be expected to work.   |
 
@@ -185,7 +185,9 @@ In [Typescript interface](#typescript-interface-for-graphic), the full interface
 
 
 Every Graphic MUST implement the following functions:
-* `load: ({}) => Promise<ReturnPayload>`: Called by the Renderer when the Graphic has been loaded into the DOM.
+* `load: ({ data:any }) => Promise<ReturnPayload>`: Called by the Renderer when the Graphic has been loaded into the DOM.
+  The `data`-payload MUST contain the initial internal state of the Graphic.
+  The schema of the `data`-payload of this function is described in the Manifest using the `schema` field.
   A Promise is returned that resolves when everything is loaded by the Graphic.
 * `dispose: ({}) => Promise<ReturnPayload>`: Called by the Renderer to force the Graphic to terminate/dispose/clear any loaded resources. A Promise
   is returned that resolves when the Graphic completed the necessary cleanup.
@@ -198,7 +200,7 @@ Every Graphic MUST implement the following functions:
 * `stopAction: ({skipAnimation: boolean}) => Promise<ReturnPayload>`: Called by the Renderer to stop the Graphic from being displayed.
   This can be with or without animation, depending on the value of the `skipAnimation` field. The returned Promise resolves to an `ReturnPayload` object.
 * `updateAction: ({ data: any }) => Promise<ReturnPayload>`: Called by the Renderer to update one or more fields of the internal state of the Graphic. The schema of the
-  payload of this function is described in the Manifest using the `schema` field. The returned Promise resolves to an `ReturnPayload` object.
+  `data`-payload of this function is described in the Manifest using the `schema` field. The returned Promise resolves to an `ReturnPayload` object.
 * `customAction: ({ id: string, payload: any}) => Promise<ReturnPayload>`: Called by the Renderer to invoke a custom action on the Graphic.
   The `id` field MUST correspond to an `id` of an Action that is defined in the Manifest file, inside the `actions` field.
   The schema for the `payload` field is the described in the corresponding Action inside the Manifest file. A Promise
@@ -271,7 +273,7 @@ The above manifest refers to the Javascript file `lower-third.mjs`, which is the
 
 ```typescript
 class Graphic extends HTMLElement {
-  async load(loadParams) {
+  async load({ data: { name: string } } ) {
     // Load resources and initialize
   }
   async dispose() {

v1-draft-0/typescript-definitions/src/apis/graphicsAPI.ts

@@ -28,6 +28,9 @@ export interface Graphic {
    */
   load: (
     params: {
+      /** The data send here is defined in the manifest "schema". Note: This data MUST HAVE the same type as the `data` argument in updateAction method. */
+      data: unknown;
+
       /** Whether the rendering is done in realtime or non-realtime */
       renderType: "realtime" | "non-realtime";
 
@@ -45,7 +48,7 @@ export interface Graphic {
   /** This is called whenever user send a new data payload. */
   updateAction: (
     params: {
-      /** The data send here is defined in the manifest "schema". */
+      /** The data send here is defined in the manifest "schema". Note: This data MUST HAVE the same type as the `data` argument in the load method.  */
       data: unknown;
     } & VendorExtend
   ) => Promise<ReturnPayload>;