Updating caching handlers (#2346)

* Fixing e2e for dialog-parent communication

* Making beforeSuspendORTerminateFunction Async

* adding delay to registerBeforeSuspendOrTerminate

* fixing unit tests

* converted contentUrl from string to URL type in resumeContext for cachign handler

* Update @microsoft-teams-js-ec870a0b-890d-4ada-b33b-301c1c28a8d3.json

* nit changefile changes

---------

Co-authored-by: AE ( ͡ಠ ʖ̯ ͡ಠ) <36546967+AE-MS@users.noreply.github.com>

apps/teams-test-app/src/components/AppAPIs.tsx

@@ -89,7 +89,7 @@ const RegisterOnResumeHandler = (): React.ReactElement => {
  app.lifecycle.registerOnResumeHandler((context: ResumeContext): void => {
  setResult('successfully called with context:' + JSON.stringify(context));
  // get the route from the context
- const route = new URL(context.contentUrl);
+ const route = context.contentUrl;
  // navigate to the correct path based on URL
  navigate(route.pathname);
  app.notifySuccess();
@@ -101,18 +101,29 @@ const RegisterOnResumeHandler = (): React.ReactElement => {
 };
 
 const RegisterBeforeSuspendOrTerminateHandler = (): React.ReactElement =>
- ApiWithoutInput({
+ ApiWithTextInput<number>({
  name: 'RegisterBeforeSuspendOrTerminateHandler',
  title: 'Register Before Suspend/Terminate Handler',
- onClick: async (setResult) => {
- app.lifecycle.registerBeforeSuspendOrTerminateHandler((): void => {
- setResult('beforeSuspendOrTerminate received');
- });
-
- return 'registered';
+ onClick: {
+ validateInput: (input) => {
+ if (typeof input !== 'number') {
+ throw new Error('input should be a number');
+ }
+ },
+ submit: async (delay: number, setResult: (result: string) => void) => {
+ app.lifecycle.registerBeforeSuspendOrTerminateHandler(() => {
+ return new Promise<void>((resolve) => {
+ setTimeout(() => {
+ setResult('beforeSuspendOrTerminate received');
+ resolve();
+ }, delay);
+ });
+ });
+ return 'registered';
+ },
  },
+ defaultInput: '3000',
  });
-
 const AppAPIs = (): ReactElement => (
  <ModuleWrapper title="App">
  <GetContext />

change/@microsoft-teams-js-ec870a0b-890d-4ada-b33b-301c1c28a8d3.json

@@ -0,0 +1,7 @@
+{
+ "type": "minor",
+ "comment": "Updated `app.lifecycle.registerBeforeSuspendOrTerminateHandler` to be asynchronous, and updated `app.lifecycle.registerOnResumeHandler` to accept a new Handler type, changing `contentUrl` from `string` to `URL` object.",
+ "packageName": "@microsoft/teams-js",
+ "email": "lakhveerkaur@microsoft.com",
+ "dependentChangeType": "patch"
+}

packages/teams-js/src/internal/handlers.ts

@@ -29,7 +29,7 @@ class HandlersPrivate {
  * @deprecated
  */
  public static beforeUnloadHandler: null | ((readyToUnload: () => void) => boolean) = null;
- public static beforeSuspendOrTerminateHandler: null | (() => void) = null;
+ public static beforeSuspendOrTerminateHandler: null | (() => Promise<void>) = null;
  public static resumeHandler: null | ((context: ResumeContext) => void) = null;
 
  /**
@@ -197,16 +197,30 @@ export function registerOnLoadHandler(apiVersionTag: string, handler: (context:
  * @internal
  * Limited to Microsoft-internal use
  */
-function handleLoad(context: LoadContext): void {
+function handleLoad(loadContext: LoadContext): void {
+ const resumeContext = convertToResumeContext(loadContext);
  if (HandlersPrivate.resumeHandler) {
- HandlersPrivate.resumeHandler(context);
+ HandlersPrivate.resumeHandler(resumeContext);
+ if (Communication.childWindow) {
+ sendMessageEventToChild('load', [resumeContext]);
+ }
  } else if (HandlersPrivate.loadHandler) {
- HandlersPrivate.loadHandler(context);
+ HandlersPrivate.loadHandler(loadContext);
+ if (Communication.childWindow) {
+ sendMessageEventToChild('load', [loadContext]);
+ }
  }
+}
 
- if (Communication.childWindow) {
- sendMessageEventToChild('load', [context]);
- }
+/**
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+function convertToResumeContext(context: LoadContext): ResumeContext {
+ return {
+ entityId: context.entityId,
+ contentUrl: new URL(context.contentUrl),
+ };
 }
 
 /**
@@ -227,13 +241,13 @@ export function registerBeforeUnloadHandler(
  * @internal
  * Limited to Microsoft-internal use
  */
-function handleBeforeUnload(): void {
+async function handleBeforeUnload(): Promise<void> {
  const readyToUnload = (): void => {
  sendMessageToParent(getApiVersionTag(ApiVersionNumber.V_2, ApiName.HandleBeforeUnload), 'readyToUnload', []);
  };
 
  if (HandlersPrivate.beforeSuspendOrTerminateHandler) {
- HandlersPrivate.beforeSuspendOrTerminateHandler();
+ await HandlersPrivate.beforeSuspendOrTerminateHandler();
  if (Communication.childWindow) {
  sendMessageEventToChild('beforeUnload');
  } else {
@@ -252,7 +266,7 @@ function handleBeforeUnload(): void {
  * @internal
  * Limited to Microsoft-internal use
  */
-export function registerBeforeSuspendOrTerminateHandler(handler: () => void): void {
+export function registerBeforeSuspendOrTerminateHandler(handler: () => Promise<void>): void {
  HandlersPrivate.beforeSuspendOrTerminateHandler = handler;
  !isNullOrUndefined(handler) &&
  sendMessageToParent(
@@ -266,7 +280,7 @@ export function registerBeforeSuspendOrTerminateHandler(handler: () => void): vo
  * @internal
  * Limited to Microsoft-internal use
  */
-export function registerOnResumeHandler(handler: (context: LoadContext) => void): void {
+export function registerOnResumeHandler(handler: (context: ResumeContext) => void): void {
  HandlersPrivate.resumeHandler = handler;
  !isNullOrUndefined(handler) &&
  sendMessageToParent(getApiVersionTag(ApiVersionNumber.V_2, ApiName.RegisterOnResumeHandler), 'registerHandler', [

packages/teams-js/src/public/app.ts

@@ -943,7 +943,7 @@ export namespace app {
  *
  * @returns void
  */
- export type registerBeforeSuspendOrTerminateHandlerFunctionType = () => void;
+ export type registerBeforeSuspendOrTerminateHandlerFunctionType = () => Promise<void>;
 
  /**
  * Registers a handler to be called before the page is suspended or terminated. Once a user navigates away from an app,

packages/teams-js/src/public/interfaces.ts

@@ -951,14 +951,24 @@ export interface ResumeContext {
  /**
  * The content URL that is requested to be loaded
  */
- contentUrl: string;
+ contentUrl: URL;
 }
 
 /**
  * @deprecated
  * As of 2.14.1, please use {@link ResumeContext} instead.
  */
-export type LoadContext = ResumeContext;
+export interface LoadContext {
+ /**
+ * The entity that is requested to be loaded
+ */
+ entityId: string;
+
+ /**
+ * The content URL that is requested to be loaded
+ */
+ contentUrl: string;
+}
 
 /** Represents information about a frame within a tab or dialog module. */
 export interface FrameInfo {

packages/teams-js/test/public/app.spec.ts

@@ -15,6 +15,7 @@ import {
  ActionObjectType,
  Context,
  FileOpenPreference,
+ LoadContext,
  M365ContentAction,
  SecondaryM365ContentIdName,
 } from '../../src/public/interfaces';
@@ -43,6 +44,10 @@ function isM365ContentType(actionItem: unknown): actionItem is M365ContentAction
 
 describe('Testing app capability', () => {
  const mockErrorMessage = 'Something went wrong...';
+ const loadContext: LoadContext = {
+ entityId: 'testEntityId',
+ contentUrl: 'https://localhost:4000',
+ };
  describe('Framed - Testing app capability', () => {
  // Use to send a mock message from the app.
  const utils = new Utils();
@@ -890,7 +895,7 @@ describe('Testing app capability', () => {
  describe('Testing app.lifecycle subcapability', () => {
  describe('Testing app.lifecycle.registerBeforeSuspendOrTerminateHandler function', () => {
  it('should not allow calls before initialization', () => {
- expect(() => app.lifecycle.registerBeforeSuspendOrTerminateHandler(() => {})).toThrowError(
+ expect(() => app.lifecycle.registerBeforeSuspendOrTerminateHandler(async () => {})).toThrowError(
  new Error(errorLibraryNotInitialized),
  );
  });
@@ -899,7 +904,7 @@ describe('Testing app capability', () => {
  it(`app.lifecycle.registerBeforeSuspendOrTerminateHandler should successfully register a beforSuspendOrTerminate handler and readyToUnload should be called. context: ${context}`, async () => {
  await utils.initializeWithContext(context);
 
- app.lifecycle.registerBeforeSuspendOrTerminateHandler(() => {});
+ app.lifecycle.registerBeforeSuspendOrTerminateHandler(async () => {});
 
  await utils.sendMessage('beforeUnload');
 
@@ -911,7 +916,7 @@ describe('Testing app capability', () => {
  describe('Testing app.lifecycle.registerOnResumeHandler function', () => {
  it('should not allow calls before initialization', () => {
  expect(() =>
- app.lifecycle.registerOnResumeHandler(() => {
+ app.lifecycle.registerOnResumeHandler(async () => {
  return false;
  }),
  ).toThrowError(new Error(errorLibraryNotInitialized));
@@ -925,8 +930,7 @@ describe('Testing app capability', () => {
  app.lifecycle.registerOnResumeHandler(() => {
  handlerInvoked = true;
  });
-
- await utils.sendMessage('load');
+ await utils.sendMessage('load', loadContext);
  expect(handlerInvoked).toBe(true);
  });
  });
@@ -1692,7 +1696,7 @@ describe('Testing app capability', () => {
  describe('Testing app.lifecycle subcapability', () => {
  describe('Testing app.lifecycle.registerBeforeSuspendOrTerminateHandler function', () => {
  it('should not allow calls before initialization', () => {
- expect(() => app.lifecycle.registerBeforeSuspendOrTerminateHandler(() => {})).toThrowError(
+ expect(() => app.lifecycle.registerBeforeSuspendOrTerminateHandler(async () => {})).toThrowError(
  new Error(errorLibraryNotInitialized),
  );
  });
@@ -1701,7 +1705,7 @@ describe('Testing app capability', () => {
  it(`app.lifecycle.registerBeforeSuspendOrTerminateHandler should successfully register a beforSuspendOrTerminate handler and readyToUnload should be called. context: ${context}`, async () => {
  await utils.initializeWithContext(context);
 
- app.lifecycle.registerBeforeSuspendOrTerminateHandler(() => {});
+ app.lifecycle.registerBeforeSuspendOrTerminateHandler(async () => {});
  await utils.respondToFramelessMessage({
  data: {
  func: 'beforeUnload',
@@ -1733,6 +1737,7 @@ describe('Testing app capability', () => {
  await utils.respondToFramelessMessage({
  data: {
  func: 'load',
+ args: [loadContext],
  },
  } as DOMMessageEvent);
  expect(handlerInvoked).toBe(true);

packages/teams-js/test/public/publicAPIs.spec.ts

@@ -3,7 +3,7 @@ import * as utilFunc from '../../src/internal/utils';
 import { app } from '../../src/public';
 import { HostClientType, TeamType, UserTeamRole } from '../../src/public/constants';
 import { FrameContexts } from '../../src/public/constants';
-import { Context, FrameContext, TabInstanceParameters } from '../../src/public/interfaces';
+import { Context, FrameContext, LoadContext, TabInstanceParameters } from '../../src/public/interfaces';
 import * as microsoftTeams from '../../src/public/publicAPIs';
 import {
  enablePrintCapability,
@@ -849,7 +849,12 @@ describe('MicrosoftTeams-publicAPIs', () => {
  return false;
  });
 
- await utils.sendMessage('load');
+ const loadContext: LoadContext = {
+ entityId: 'testEntityId',
+ contentUrl: 'https://localhost:4000',
+ };
+
+ await utils.sendMessage('load', loadContext);
 
  expect(handlerInvoked).toBe(true);
  });

packages/teams-js/test/public/teamsAPIs.spec.ts

@@ -1,4 +1,5 @@
 import { errorLibraryNotInitialized } from '../../src/internal/constants';
+import { LoadContext } from '../../src/public';
 import { app } from '../../src/public/app';
 import { errorNotSupportedOnPlatform, FrameContexts } from '../../src/public/constants';
 import { _minRuntimeConfigToUninitialize } from '../../src/public/runtime';
@@ -32,6 +33,11 @@ describe('Testing TeamsCore Capability', () => {
  }
  });
 
+ const loadContext: LoadContext = {
+ entityId: 'testEntityId',
+ contentUrl: 'https://localhost:4000',
+ };
+
  describe('Testing teamsCore.isSupported function', () => {
  it('should throw if called before initialization', () => {
  utils.uninitializeRuntimeConfig();
@@ -164,7 +170,7 @@ describe('Testing TeamsCore Capability', () => {
  return false;
  });
 
- await utils.sendMessage('load');
+ await utils.sendMessage('load', loadContext);
 
  expect(handlerInvoked).toBe(true);
  });