https://github.com/matrix-org/matrix-widget-api

JavaScript/TypeScript API for widgets & web clients to communicate
https://github.com/matrix-org/matrix-widget-api

hacktoberfest matrix matrix-widget-api widgets

Last synced: 5 days ago
JSON representation

JavaScript/TypeScript API for widgets & web clients to communicate

• Host: GitHub
• URL: https://github.com/matrix-org/matrix-widget-api
• Owner: matrix-org
• License: apache-2.0
• Created: 2020-09-04T19:11:03.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2024-12-06T19:53:58.000Z (7 days ago)
• Last Synced: 2024-12-06T20:06:55.110Z (7 days ago)
• Topics: hacktoberfest, matrix, matrix-widget-api, widgets
• Language: TypeScript
• Homepage:
• Size: 690 KB
• Stars: 60
• Watchers: 22
• Forks: 19
• Open Issues: 34
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE
  • Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

• awesome-matrix - matrix-widget-api - A widget (Widgets / 2016)

README

        
# matrix-widget-api

![npm](https://img.shields.io/npm/v/matrix-widget-api?style=for-the-badge)

JavaScript/TypeScript SDK for widgets & clients to communicate.

For help and support, visit [#matrix-widgets:matrix.org](https://matrix.to/#/#matrix-widgets:matrix.org) on Matrix.

*Disclaimer: Widgets are not yet in the Matrix spec, so this library may not work with other implementations.*

## Building

To transpile this project to JavaScript, run:

```

yarn install

yarn build

```

## Using the API without a bundler

If you're looking to drop the widget-api into a web browser without the use of a bundler, add a `script`

tag similar to the following:

```html

```

Note that the version number may need changing to match the current release.

Once included, the widget-api will be available under `mxwidgets`. For example, `new mxwidgets.WidgetApi(...)`

to instantiate the `WidgetApi` class.

## Usage for widgets

The general usage for this would be:

```typescript

const widgetId = null; // if you know the widget ID, supply it.

const api = new WidgetApi(widgetId);

// Before doing anything else, request capabilities:

api.requestCapability(MatrixCapabilities.Screenshots);

api.requestCapabilities(StickerpickerCapabilities);

// Add custom action handlers (if needed)

api.on(`action:${WidgetApiToWidgetAction.UpdateVisibility}`, (ev: CustomEvent) => {

    ev.preventDefault(); // we're handling it, so stop the widget API from doing something.

    console.log(ev.detail); // custom handling here

    api.transport.reply(ev.detail, {});

});

api.on("action:com.example.my_action", (ev: CustomEvent) => {

    ev.preventDefault(); // we're handling it, so stop the widget API from doing something.

    console.log(ev.detail); // custom handling here

    api.transport.reply(ev.detail, {custom: "reply"});

});

// Start the messaging

api.start();

// If waitForIframeLoad is false, tell the client that we're good to go

api.sendContentLoaded();

// Later, do something else (if needed)

api.setAlwaysOnScreen(true);

api.transport.send("com.example.my_action", {isExample: true});

```

For a more complete example, see the `examples` directory of this repo.

## Usage for web clients

This SDK is meant for use in browser-based applications. The concepts may be transferable to other platforms,

though currently this SDK is intended to only be used by browsers. In the future it may be possible for this

SDK to provide an interface for other platforms.

TODO: Improve this

```typescript

const driver = new CustomDriver(); // an implementation of WidgetDriver

const api = new ClientWidgetApi(widget, iframe, driver);

// The API is automatically started, so we just have to wait for a ready before doing something

api.on("ready", () => {

    api.updateVisibility(true).then(() => console.log("Widget knows it is visible now"));

    api.transport.send("com.example.my_action", {isExample: true});

});

// Eventually, stop the API handling

api.stop();

```