Matrix Widget Starter

Anleitung

Dieses Dokument dient als Leitfaden für den Workshop. Es kann der Reihe nach eigenständig durchgearbeitet werden. Ziel ist es nach dem Workshop ein einfaches Widget am Laufen zu haben.

Wenn Fragen bestehen einfach melden :)

Voraussetzungen

• JavaScript / TypeScript Kenntnisse
• Node.js >= 20.0 und yarn
• Element Web Client (zur Entwicklung, weil selbst signierte Zertifikate benutzt werden)

Links

MSC2764 spezifiziert Widgets. Die Spezifikation wird bereits genutzt, ist aber immer noch nicht final!

Das matrix-widget-toolkit vereinfacht die Umsetzung eines Widgets.

Beispiele für Widgets

• NeoBoard - Ein kollaboratives Whiteboard
• NeoDateFix Meetings in Matrix planen
• Matrix BarCamp - Ein BarCamp in Matrix organisieren
• Matrix Planning Poker - Ein Planning Poker Widget

Matrix Widget Toolkit als Beispiel

Zuerst das matrix-widget-toolkit Git Repo clonen und die Abhängigkeiten installieren

git clone https://github.com/nordeck/matrix-widget-toolkit.git
yarn 

Dann das Beispiel unter /example-widget-mui starten:

cd example-widget-mui
yarn start

Es sollte so etwas, wie das folgende angezeigt werden:

Compiled successfully!

You can now view @matrix-widget-toolkit/example-widget-mui in the browser.

  Local:            https://localhost:3000

Die URL aufrufen und das selbst signierte Zertifikat bestätigen.

In Element einen Matrix Raum erstellen, zum Beispiel „GPN Widget Workshop“. Darin dann den Befehl aus der Widget URL abschicken. Zum Beispiel

/addwidget https://localhost:3000/

Gegebenenfalls in den Raumeinstellungen das Widget anpinnen:

Berechtigungen bestätigen und Registrierung korrigieren anklicken. Danach den Raum wechseln und wieder anzeigen.

Die Widget-Demo sollte jetzt angezeigt werden.

Die Beispiele zeigen viel von dem, was das Widget Toolkit kann.

Widget „Hello World“

Jetzt wird ein eigenes Widget gebaut. Ziel ist es eine Nachricht in den Raum zu schicken und Nachrichten im Raum zu lesen.

Im Verzeichnis ./widget-hello-world befindet sich das grundlegende Setup eines Widgets mit dem matrix-widget-toolkit.

In der main.tsx werden die initialen Berechtigungen festgelegt. Für das „Hello World“ sind das empfangen und senden von Nachrichten in einem Raum.

Am Besten einmal in das Verzeichnis wechseln und ausprobieren, ob es klappt:

cd widget-hello-world
npm install
npm run dev:https

Dann die URL im Browser öffnen, das Zertifikat bestätigen. Danach sollte der folgende Hinweis sichtbar sein:

Damit kann das Widget, analog zu oben, einem Raum hinzugefügt werden. Es sollte sowas angezeigt werden:

Nachricht senden

Nachricht senden wird von der Komponente ./widget-hello-world/src/components/SendMessage.tsx erledigt. Zuerst muss die Widget API eingebunden werden. Dazu das hier einfügen:

Ganz oben bei den Imports:

import { useWidgetApi } from "@matrix-widget-toolkit/react";

Unter export const SendMessage… => {:

const widgetApi = useWidgetApi();

Jetzt kann bei einem Klick auf den Button die Nachricht geschickt werden.

Dazu das hier bei den Imports einfügen:

import { ROOM_EVENT_ROOM_MESSAGE, RoomMessageEvent } from "../events";

Und in handleSubmit hinter den if-Block die Nachricht schicken:

// Nachricht über die Widget API senden
await widgetApi.sendRoomEvent<RoomMessageEvent>(ROOM_EVENT_ROOM_MESSAGE, {
  msgtype: "m.text",
  body: message,
});

Jetzt sollte es möglich sein, eine Nachricht aus dem Widget in den Raum zu schicken.

Nachrichten empfangen

Die Komponente ShowMessages soll die Nachrichten im Raum anzeigen. Hier ist die Widget API schon eingebunden.

Um an die Nachrichten zu kommen, kann über die Widget API ein Observer registriert werden.

Dazu bei den Imports das hier einfügen:

import {
  ROOM_EVENT_ROOM_MESSAGE,
  RoomMessageEvent,
  isValidRoomMessageEvent,
} from "../events";
import { filter } from "rxjs";

Das hier in den useEffect Block einfügen:

const subscription = widgetApi
  // Auf room messages hören
  .observeRoomEvents(ROOM_EVENT_ROOM_MESSAGE)
  // Eingehende Nachrichten filtern, damit nur das richtige ankommt
  .pipe(filter(isValidRoomMessageEvent))
  // Nachrichten im State der Komponente speichern
  .subscribe((message) => {
    setMessages((messages) => [...messages, message]);
  });

// Funktionen, die in einem useEffect zurückgegeben werden,
// werden beim unmount der Komponente ausgeführt.
return () => {
  // Subscription bei unmount der Komponente abbestellen.
  subscription.unsubscribe();
};

Das war der Matrix Widget Starter Workshop :) Danke fürs Mitmachen und viel Spaß beim Bauen von Widgets!