From bb0be4ba726ec4529e999319752705dc6a859d11 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Thu, 22 Jul 2021 15:43:18 -0600
Subject: [PATCH] Add customisation point for declaring widget variables

Fixes https://github.com/vector-im/element-web/issues/18035 (indirectly; issue is on a non-standard version of Element).

This has an isReady() step because the variable usage code path cannot be made async, so instead we let the async loading state happen in the prepare() stage. This is required for the intended usecase.
---
 src/customisations/WidgetVariables.ts | 53 +++++++++++++++++++++++++++
 src/stores/widgets/StopGapWidget.ts   | 10 ++++-
 2 files changed, 61 insertions(+), 2 deletions(-)
 create mode 100644 src/customisations/WidgetVariables.ts

diff --git a/src/customisations/WidgetVariables.ts b/src/customisations/WidgetVariables.ts
new file mode 100644
index 00000000000..db3a56436d8
--- /dev/null
+++ b/src/customisations/WidgetVariables.ts
@@ -0,0 +1,53 @@
+/*
+ * Copyright 2021 The Matrix.org Foundation C.I.C.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Populate this class with the details of your customisations when copying it.
+import { ITemplateParams } from "matrix-widget-api";
+
+/**
+ * Provides a partial set of the variables needed to render any widget. If
+ * variables are missing or not provided then they will be filled with the
+ * application-determined defaults.
+ *
+ * This will not be called until after isReady() resolves.
+ * @returns {Partial<Omit<ITemplateParams, "widgetRoomId">>} The variables.
+ */
+function provideVariables(): Partial<Omit<ITemplateParams, "widgetRoomId">> {
+    return {};
+}
+
+/**
+ * Resolves to whether or not the customisation point is ready for variables
+ * to be provided. This will block widgets being rendered.
+ * @returns {Promise<boolean>} Resolves when ready.
+ */
+async function isReady(): Promise<void> {
+    return; // default no waiting
+}
+
+// This interface summarises all available customisation points and also marks
+// them all as optional. This allows customisers to only define and export the
+// customisations they need while still maintaining type safety.
+export interface IWidgetVariablesCustomisations {
+    provideVariables?: typeof provideVariables;
+
+    // If not provided, the app will assume that the customisation is always ready.
+    isReady?: typeof isReady;
+}
+
+// A real customisation module will define and export one or more of the
+// customisation points that make up the interface above.
+export const WidgetVariableCustomisations: IWidgetVariablesCustomisations = {};
diff --git a/src/stores/widgets/StopGapWidget.ts b/src/stores/widgets/StopGapWidget.ts
index 24869b5edc6..daa1e0e7873 100644
--- a/src/stores/widgets/StopGapWidget.ts
+++ b/src/stores/widgets/StopGapWidget.ts
@@ -54,6 +54,7 @@ import { ElementWidgetCapabilities } from "./ElementWidgetCapabilities";
 import { MatrixEvent } from "matrix-js-sdk/src/models/event";
 import { ELEMENT_CLIENT_ID } from "../../identifiers";
 import { getUserLanguage } from "../../languageHandler";
+import { WidgetVariableCustomisations } from "../../customisations/WidgetVariables";
 
 // TODO: Destroy all of this code
 
@@ -191,7 +192,8 @@ export class StopGapWidget extends EventEmitter {
     }
 
     private runUrlTemplate(opts = { asPopout: false }): string {
-        const templated = this.mockWidget.getCompleteUrl({
+        const fromCustomisation = WidgetVariableCustomisations?.provideVariables?.() ?? {};
+        const defaults: ITemplateParams = {
             widgetRoomId: this.roomId,
             currentUserId: MatrixClientPeg.get().getUserId(),
             userDisplayName: OwnProfileStore.instance.displayName,
@@ -199,7 +201,8 @@ export class StopGapWidget extends EventEmitter {
             clientId: ELEMENT_CLIENT_ID,
             clientTheme: SettingsStore.getValue("theme"),
             clientLanguage: getUserLanguage(),
-        }, opts?.asPopout);
+        };
+        const templated = this.mockWidget.getCompleteUrl(Object.assign(defaults, fromCustomisation), opts?.asPopout);
 
         const parsed = new URL(templated);
 
@@ -363,6 +366,9 @@ export class StopGapWidget extends EventEmitter {
     }
 
     public async prepare(): Promise<void> {
+        // Ensure the variables are ready for us to be rendered before continuing
+        await (WidgetVariableCustomisations?.isReady?.() ?? Promise.resolve());
+
         if (this.scalarToken) return;
         const existingMessaging = WidgetMessagingStore.instance.getMessaging(this.mockWidget);
         if (existingMessaging) this.messaging = existingMessaging;