This is an example that shows how you can write a Matrix/Element widget. You can use this package as a starting point for writing new widgets.
The widget demonstrates:
- How to use the available Widget parameters (
Welcome
). - How to obtain and verify an OIDC token (
Identity
). - How to receive and send room events (
Dice
). - How to receive and send state events (
Room Admin Tool
). - How to read data from all rooms (
All Rooms
). - How to open widget modals (
Modal
). - How to use Redux for state management (
Power Levels
). - How to read related events (
Event Relations
). - How to search the User Directory (
User Directory and Invitations
). - How to use the UI components to match the style of Element (
Theme
). - How to upload and download files to the media repository (
Up- and download image
).
Click here and follow the instructions to see it in action.
You should have a local Node.js LTS development environment setup with yarn
available. Then execute the following commands in your terminal:
git clone https://github.com/nordeck/matrix-widget-toolkit.git
cd matrix-widget-toolkit && yarn install
After this, you can run the example widget locally with the following commands:
yarn dev:example
: Start the example app.yarn dev:example:https
: Start the example app with a self-signed HTTPS certificate.
The example widget is embedded into the widget host as an iframe. This can cause mixed-content errors if your local widget is served without HTTPS but the Element hosting it is running with HTTPS. You have multiple options to solve them:
- Run an own copy of
element-web
locally (e.g. via Docker or by buildingelement-web
from source), without HTTPS and start the widget viayarn dev
. - Run your Chrome instance with
--allow-insecure-localhost --disable-site-isolation-trials --disable-web-security
to disable mixed-content errors, use any Element, and start the widget viayarn start
(with HTTPS).Warning Do not use this Chrome instance to browse the web!
- Use a tunneling service such as
localtunnel
orngrok
to run the widget with a valid HTTPS certificate, use any Element, and start the widget viayarn dev
. This way Chrome behaves closest to how it would behave in production.
Then visit the printed URL and follow the instructions on the page to setup the widget.