Templatable document title

docs/config.md

@@ -212,6 +212,20 @@ Starting with `branding`, the following subproperties are available:
 3. `auth_footer_links`: A list of links to add to the footer during login, registration, etc. Each entry must have a `text` and
    `url` property.
 
+
+4. `title_template`: A template string that can be used to configure the title of the application when not viewing a room.
+5. `title_template_in_room`: A template string that can be used to configure the title of the application when viewing a room
+
+#### `title_template` vars
+
+- `brand` The name of the web app, as configured by the `brand` config value.
+- `room_name` The friendly name of a room. Only applicable to `title_template_in_room`.
+- `status` The client's status, repesented as. 
+  - The notification count, when at least one room is unread.
+  - "*" when no rooms are unread, but notifications are not muted.
+  - "Offline", when the client is offline.
+  - "", when the client isn't logged in or notifications are muted.
+
 `embedded_pages` can be configured as such:
 
 1. `welcome_url`: A URL to an HTML page to show as a welcome page (landing on `#/welcome`). When not specified, the default

playwright/e2e/branding/title.spec.ts

@@ -0,0 +1,46 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { expect, test } from "../../element-web-test";
+
+/*
+ * Tests for branding configuration
+ **/
+
+test.describe('Test without branding config', () => {
+    test("Shows standard branding when showing the home page", async ({ pageWithCredentials: page }) => {
+        await page.goto("/");
+        await page.waitForSelector(".mx_MatrixChat", { timeout: 30000 });
+        expect(page.title()).toEqual('Element *');
+    });
+    test("Shows standard branding when showing a room", async ({ app, pageWithCredentials: page }) => {
+        await app.client.createRoom({ name: "Test Room" });
+        await app.viewRoomByName("Test Room");
+        expect(page.title()).toEqual('Element * | Test Room');
+    });
+});
+
+test.describe('Test with custom branding', () => {
+    test.use({ config: {
+        brand: 'TestBrand',
+        branding: {
+            title_template: 'TestingApp $ignoredParameter $brand $status $ignoredParameter',
+            title_template_in_room: 'TestingApp $brand $status $room_name $ignoredParameter'
+        }
+    }});
+    test("Shows custom branding when showing the home page", async ({ pageWithCredentials: page }) => {
+        await page.goto("/");
+        await page.waitForSelector(".mx_MatrixChat", { timeout: 30000 });
+        expect(page.title()).toEqual('TestingApp TestBrand * $ignoredParameter');
+    });
+    test("Shows custom branding when showing a room", async ({ app, pageWithCredentials: page }) => {
+        await app.client.createRoom({ name: "Test Room" });
+        await app.viewRoomByName("Test Room");
+        expect(page.title()).toEqual('TestingApp TestBrand * Test Room $ignoredParameter');
+    });
+});
+

src/IConfigOptions.ts

@@ -50,6 +50,8 @@ export interface IConfigOptions {
         welcome_background_url?: string | string[]; // chosen at random if array
         auth_header_logo_url?: string;
         auth_footer_links?: { text: string; url: string }[];
+        title_template?: string;
+        title_template_in_room?: string;
     };
 
     force_verification?: boolean; // if true, users must verify new logins

src/components/structures/MatrixChat.tsx

@@ -228,6 +228,9 @@ export default class MatrixChat extends React.PureComponent<IProps, IState> {
     private subTitleStatus: string;
     private prevWindowWidth: number;
 
+    private readonly titleTemplate: string;
+    private readonly titleTemplateInRoom: string;
+
     private readonly loggedInView = createRef<LoggedInViewType>();
     private dispatcherRef?: string;
     private themeWatcher?: ThemeWatcher;
@@ -281,6 +284,9 @@ export default class MatrixChat extends React.PureComponent<IProps, IState> {
         // object field used for tracking the status info appended to the title tag.
         // we don't do it as react state as i'm scared about triggering needless react refreshes.
         this.subTitleStatus = "";
+
+        this.titleTemplate = props.config.branding?.title_template ?? '$brand $status';
+        this.titleTemplateInRoom = props.config.branding?.title_template_in_room ?? '$brand $status | $room_name';
     }
 
     /**
@@ -1106,6 +1112,7 @@ export default class MatrixChat extends React.PureComponent<IProps, IState> {
         }
         this.setStateForNewView({
             view: Views.WELCOME,
+            currentRoomId: null,
         });
         this.notifyNewScreen("welcome");
         ThemeController.isLogin = true;
@@ -1115,6 +1122,7 @@ export default class MatrixChat extends React.PureComponent<IProps, IState> {
     private viewLogin(otherState?: any): void {
         this.setStateForNewView({
             view: Views.LOGIN,
+            currentRoomId: null,
             ...otherState,
         });
         this.notifyNewScreen("login");
@@ -1949,21 +1957,32 @@ export default class MatrixChat extends React.PureComponent<IProps, IState> {
         });
     }
 
-    private setPageSubtitle(subtitle = ""): void {
+    private setPageSubtitle(): void {
+        const params: {
+            $brand: string;
+            $status: string;
+            $room_name: string|undefined;
+        } = {
+            $brand: SdkConfig.get().brand,
+            $status: this.subTitleStatus,
+            $room_name: undefined,
+        };
+
         if (this.state.currentRoomId) {
             const client = MatrixClientPeg.get();
             const room = client?.getRoom(this.state.currentRoomId);
             if (room) {
-                subtitle = `${this.subTitleStatus} | ${room.name} ${subtitle}`;
+                params.$room_name = room.name;
             }
-        } else {
-            subtitle = `${this.subTitleStatus} ${subtitle}`;
         }
+
+        const titleTemplate = params.$room_name ? this.titleTemplateInRoom : this.titleTemplate;
 
-        const title = `${SdkConfig.get().brand} ${subtitle}`;
+        const title = Object.entries(params).reduce(
+            (title: string, [key, value]) => title.replaceAll(key, (value ?? '').replaceAll('$', '$_DLR$')), titleTemplate);
 
         if (document.title !== title) {
-            document.title = title;
+            document.title = title.replaceAll('$_DLR$', '$');
         }
     }