Merge pull request #912 from concord-consortium/181169438-add-options…

…-to-get-interactive-state Added unloading option to get interactive state [#181169438]
concord-consortium · Mar 8, 2022 · f305b99 · f305b99
2 parents 74a29d7 + 1207c95
commit f305b99
Show file tree

Hide file tree

Showing 11 changed files with 5,448 additions and 5,140 deletions.
diff --git a/docs/interactive-api-client/classes/client.md b/docs/interactive-api-client/classes/client.md
@@ -29,6 +29,7 @@
 * [removeDecorateContentListener](client.md#removedecoratecontentlistener)
 * [removeGetReportItemAnswerListener](client.md#removegetreportitemanswerlistener)
 * [removeListener](client.md#removelistener)
+* [setOnUnload](client.md#setonunload)
 * [setSupportedFeatures](client.md#setsupportedfeatures)
 
 ## Constructors
@@ -175,6 +176,20 @@ Name | Type |
 
 ___
 
+###  setOnUnload
+
+▸ **setOnUnload**(`onUnload?`: [OnUnloadFunction](../globals.md#onunloadfunction)): *void*
+
+**Parameters:**
+
+Name | Type |
+------ | ------ |
+`onUnload?` | [OnUnloadFunction](../globals.md#onunloadfunction) |
+
+**Returns:** *void*
+
+___
+
 ###  setSupportedFeatures
 
 ▸ **setSupportedFeatures**(`request`: [ISupportedFeaturesRequest](../interfaces/isupportedfeaturesrequest.md)): *void*

diff --git a/docs/interactive-api-client/globals.md b/docs/interactive-api-client/globals.md
@@ -44,6 +44,7 @@
 * [IGetInteractiveSnapshotOptions](interfaces/igetinteractivesnapshotoptions.md)
 * [IGetInteractiveSnapshotRequest](interfaces/igetinteractivesnapshotrequest.md)
 * [IGetInteractiveSnapshotResponse](interfaces/igetinteractivesnapshotresponse.md)
+* [IGetInteractiveState](interfaces/igetinteractivestate.md)
 * [IGetLibraryInteractiveListOptions](interfaces/igetlibraryinteractivelistoptions.md)
 * [IGetLibraryInteractiveListRequest](interfaces/igetlibraryinteractivelistrequest.md)
 * [IGetLibraryInteractiveListResponse](interfaces/igetlibraryinteractivelistresponse.md)
@@ -113,6 +114,7 @@
 * [InteractiveItemId](globals.md#interactiveitemid)
 * [LoggerClientMessage](globals.md#loggerclientmessage)
 * [ModalType](globals.md#modaltype)
+* [OnUnloadFunction](globals.md#onunloadfunction)
 * [ReadAttachmentParams](globals.md#readattachmentparams)
 * [ServerMessage](globals.md#servermessage)
 * [WriteAttachmentParams](globals.md#writeattachmentparams)
@@ -163,6 +165,7 @@
 * [setInteractiveState](globals.md#const-setinteractivestate)
 * [setLinkedInteractives](globals.md#const-setlinkedinteractives)
 * [setNavigation](globals.md#const-setnavigation)
+* [setOnUnload](globals.md#const-setonunload)
 * [setSupportedFeatures](globals.md#const-setsupportedfeatures)
 * [showModal](globals.md#const-showmodal)
 * [useAuthoredState](globals.md#const-useauthoredstate)
@@ -368,6 +371,22 @@ ___
 
 ___
 
+###  OnUnloadFunction
+
+Ƭ **OnUnloadFunction**: *function*
+
+#### Type declaration:
+
+▸ (`options`: [IGetInteractiveState](interfaces/igetinteractivestate.md)): *Promise‹InteractiveState›*
+
+**Parameters:**
+
+Name | Type |
+------ | ------ |
+`options` | [IGetInteractiveState](interfaces/igetinteractivestate.md) |
+
+___
+
 ###  ReadAttachmentParams
 
 Ƭ **ReadAttachmentParams**: *Omit‹[IAttachmentUrlRequest](interfaces/iattachmenturlrequest.md), "requestId" | "operation" | "contentType" | "expiresIn"›*
@@ -1055,6 +1074,20 @@ Name | Type |
 
 ___
 
+### `Const` setOnUnload
+
+▸ **setOnUnload**(`onUnload?`: [OnUnloadFunction](globals.md#onunloadfunction)): *void*
+
+**Parameters:**
+
+Name | Type |
+------ | ------ |
+`onUnload?` | [OnUnloadFunction](globals.md#onunloadfunction) |
+
+**Returns:** *void*
+
+___
+
 ### `Const` setSupportedFeatures
 
 ▸ **setSupportedFeatures**(`features`: [ISupportedFeatures](interfaces/isupportedfeatures.md)): *void*

diff --git a/docs/interactive-api-client/interfaces/igetinteractivestate.md b/docs/interactive-api-client/interfaces/igetinteractivestate.md
@@ -0,0 +1,19 @@
+[@concord-consortium/lara-interactive-api](../README.md) › [Globals](../globals.md) › [IGetInteractiveState](igetinteractivestate.md)
+
+# Interface: IGetInteractiveState
+
+## Hierarchy
+
+* **IGetInteractiveState**
+
+## Index
+
+### Properties
+
+* [unloading](igetinteractivestate.md#optional-unloading)
+
+## Properties
+
+### `Optional` unloading
+
+• **unloading**? : *undefined | false | true*
diff --git a/docs/interactive-api-host/globals.md b/docs/interactive-api-host/globals.md
@@ -37,6 +37,7 @@
 * [IGetInteractiveSnapshotOptions](interfaces/igetinteractivesnapshotoptions.md)
 * [IGetInteractiveSnapshotRequest](interfaces/igetinteractivesnapshotrequest.md)
 * [IGetInteractiveSnapshotResponse](interfaces/igetinteractivesnapshotresponse.md)
+* [IGetInteractiveState](interfaces/igetinteractivestate.md)
 * [IGetLibraryInteractiveListOptions](interfaces/igetlibraryinteractivelistoptions.md)
 * [IGetLibraryInteractiveListRequest](interfaces/igetlibraryinteractivelistrequest.md)
 * [IGetLibraryInteractiveListResponse](interfaces/igetlibraryinteractivelistresponse.md)
@@ -103,6 +104,7 @@
 * [InteractiveItemId](globals.md#interactiveitemid)
 * [LoggerClientMessage](globals.md#loggerclientmessage)
 * [ModalType](globals.md#modaltype)
+* [OnUnloadFunction](globals.md#onunloadfunction)
 * [ReadAttachmentParams](globals.md#readattachmentparams)
 * [S3Operation](globals.md#s3operation)
 * [ServerMessage](globals.md#servermessage)
@@ -296,6 +298,22 @@ ___
 
 ___
 
+###  OnUnloadFunction
+
+Ƭ **OnUnloadFunction**: *function*
+
+#### Type declaration:
+
+▸ (`options`: [IGetInteractiveState](interfaces/igetinteractivestate.md)): *Promise‹InteractiveState›*
+
+**Parameters:**
+
+Name | Type |
+------ | ------ |
+`options` | [IGetInteractiveState](interfaces/igetinteractivestate.md) |
+
+___
+
 ###  ReadAttachmentParams
 
 Ƭ **ReadAttachmentParams**: *Omit‹[IAttachmentUrlRequest](interfaces/iattachmenturlrequest.md), "requestId" | "operation" | "contentType" | "expiresIn"›*

diff --git a/docs/interactive-api-host/interfaces/igetinteractivestate.md b/docs/interactive-api-host/interfaces/igetinteractivestate.md
@@ -0,0 +1,19 @@
+[@concord-consortium/interactive-api-host](../README.md) › [Globals](../globals.md) › [IGetInteractiveState](igetinteractivestate.md)
+
+# Interface: IGetInteractiveState
+
+## Hierarchy
+
+* **IGetInteractiveState**
+
+## Index
+
+### Properties
+
+* [unloading](igetinteractivestate.md#optional-unloading)
+
+## Properties
+
+### `Optional` unloading
+
+• **unloading**? : *undefined | false | true*
diff --git a/lara-typescript/src/interactive-api-client/api.ts b/lara-typescript/src/interactive-api-client/api.ts
@@ -34,7 +34,8 @@ import {
   ReadAttachmentParams,
   GetAttachmentUrlParams,
   IGetReportItemAnswerHandler,
-  IReportItemAnswer
+  IReportItemAnswer,
+  OnUnloadFunction
 } from "./types";
 import { getClient } from "./client";
 import { v4 as uuidv4 } from "uuid";
@@ -483,3 +484,7 @@ export const getAttachmentUrl = (params: GetAttachmentUrlParams) => {
 export const sendReportItemAnswer = (request: Omit<IReportItemAnswer, "requestId">) => {
   getClient().post("reportItemAnswer", request);
 };
+
+export const setOnUnload = (onUnload?: OnUnloadFunction) => {
+  getClient().setOnUnload(onUnload);
+};
diff --git a/lara-typescript/src/interactive-api-client/client.ts b/lara-typescript/src/interactive-api-client/client.ts
@@ -3,9 +3,9 @@
 // to the same message and auto-removing listeners when a requestId is given.
 import * as iframePhone from "iframe-phone";
 import { ClientMessage, ICustomMessageHandler, ICustomMessagesHandledMap, IInitInteractive, ISupportedFeaturesRequest,
-        ServerMessage, ITextDecorationHandler, ITextDecorationInfo, IGetReportItemAnswerHandler } from "./types";
+         ServerMessage, ITextDecorationHandler, ITextDecorationInfo, IGetReportItemAnswerHandler,
+         IGetInteractiveState, OnUnloadFunction } from "./types";
 import { postDecoratedContentEvent } from "../interactive-api-client";
-import { IEventListener } from "../plugin-api";
 import { inIframe } from "./in-frame";
 import { ManagedState } from "./managed-state";
 
@@ -47,6 +47,8 @@ export class Client {
   private listeners: IListenerMap = {};
   private requestId = 1;
 
+  private onUnload: OnUnloadFunction | undefined = undefined;
+
   constructor() {
     if (!inIframe()) {
       // tslint:disable-next-line:no-console
@@ -188,6 +190,10 @@ export class Client {
     this.post("supportedFeatures", newRequest);
   }
 
+  public setOnUnload = (onUnload?: OnUnloadFunction) => {
+    this.onUnload = onUnload;
+  }
+
   private connect() {
     this.phone = iframePhone.getIFrameEndpoint();
 
@@ -212,7 +218,15 @@ export class Client {
       }
     });
 
-    this.addListener("getInteractiveState", () => {
+    this.addListener("getInteractiveState", async (options?: IGetInteractiveState) => {
+      if (options?.unloading && this.onUnload) {
+        // call the interactive's registered onUnload function
+        // and if it returns a value use that as the final interactive state
+        const finalState = await this.onUnload(options);
+        if (finalState) {
+          this.managedState.interactiveState = finalState;
+        }
+      }
       this.post("interactiveState", this.managedState.interactiveState);
       this.managedState.interactiveStateDirty = false;
     });

diff --git a/lara-typescript/src/interactive-api-shared/types.ts b/lara-typescript/src/interactive-api-shared/types.ts
@@ -509,3 +509,8 @@ export interface IDataset {
 export interface IInteractiveStateWithDataset {
   dataset?: IDataset | null;
 }
+
+export interface IGetInteractiveState {
+  unloading?: boolean;  // set to true to tell the interactive it is getting the final state
+}
+export type OnUnloadFunction<InteractiveState = {}> = (options: IGetInteractiveState) => Promise<InteractiveState>;