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

@@ -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 = {};

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;