268 lines
8.3 KiB
Markdown
268 lines
8.3 KiB
Markdown
---
|
|
sidebar_position: 11
|
|
---
|
|
|
|
# UI API
|
|
|
|
The UI API lets plugins add pages, settings pages, side panels, channel sections, actions, embed renderers, and controlled DOM mounts.
|
|
|
|
Prefer registered UI contributions over direct DOM mounting. Contribution APIs let Angular render the plugin UI when the matching app surface exists. Direct DOM mounting runs immediately and throws if the target selector is not present.
|
|
|
|
## Required Capabilities
|
|
|
|
| Method | Capability |
|
|
| --------------------------------------------- | -------------------- |
|
|
| `ui.registerAppPage(id, contribution)` | `ui.pages` |
|
|
| `ui.registerSettingsPage(id, contribution)` | `ui.settings` |
|
|
| `ui.registerSidePanel(id, contribution)` | `ui.sidePanel` |
|
|
| `ui.registerChannelSection(id, contribution)` | `ui.channelsSection` |
|
|
| `ui.registerComposerAction(id, contribution)` | `ui.pages` |
|
|
| `ui.registerProfileAction(id, contribution)` | `ui.pages` |
|
|
| `ui.registerToolbarAction(id, contribution)` | `ui.pages` |
|
|
| `ui.registerEmbedRenderer(id, contribution)` | `ui.embeds` |
|
|
| `ui.mountElement(id, request)` | `ui.dom` |
|
|
|
|
Every registration returns a disposable. Push it into `context.subscriptions`.
|
|
|
|
## App Page
|
|
|
|
```js
|
|
export function activate(context) {
|
|
context.subscriptions.push(
|
|
context.api.ui.registerAppPage('dashboard', {
|
|
label: 'Raid Dashboard',
|
|
path: '/plugins/example.raid-helper/dashboard',
|
|
render: () => {
|
|
const root = document.createElement('section');
|
|
root.innerHTML = '<h1>Raid Dashboard</h1><p>Tonight: dungeon practice.</p>';
|
|
return root;
|
|
}
|
|
})
|
|
);
|
|
}
|
|
```
|
|
|
|
The page is hosted by `/plugins/:pluginId/:pageId`.
|
|
|
|
## Settings Page
|
|
|
|
```js
|
|
export function activate(context) {
|
|
context.subscriptions.push(
|
|
context.api.ui.registerSettingsPage('preferences', {
|
|
label: 'Raid Helper',
|
|
settingsKey: 'raid-helper',
|
|
order: 20,
|
|
render: () => {
|
|
const wrapper = document.createElement('section');
|
|
const label = document.createElement('label');
|
|
const checkbox = document.createElement('input');
|
|
|
|
checkbox.type = 'checkbox';
|
|
checkbox.checked = true;
|
|
label.append(checkbox, ' Enable ready-check reminders');
|
|
wrapper.append(label);
|
|
return wrapper;
|
|
}
|
|
})
|
|
);
|
|
}
|
|
```
|
|
|
|
## Side Panel
|
|
|
|
Use `ui.registerSidePanel` for content that belongs in the server sidebar plugin area. Do not mount directly into `[data-testid="plugin-room-side-panel"]`; that host is route-specific and may not exist during plugin activation.
|
|
|
|
```js
|
|
export function activate(context) {
|
|
context.subscriptions.push(
|
|
context.api.ui.registerSidePanel('soundboard', {
|
|
label: 'Soundboard',
|
|
order: 10,
|
|
render: () => {
|
|
const panel = document.createElement('div');
|
|
const button = document.createElement('button');
|
|
|
|
button.type = 'button';
|
|
button.textContent = 'Play chime';
|
|
button.onclick = () =>
|
|
context.api.media.playAudioClip({
|
|
url: 'https://cdn.example.com/chime.wav',
|
|
volume: 0.6
|
|
});
|
|
panel.append(button);
|
|
return panel;
|
|
}
|
|
})
|
|
);
|
|
}
|
|
```
|
|
|
|
Capabilities required: `ui.sidePanel` and `media.playAudio`.
|
|
|
|
## Channel Section
|
|
|
|
```js
|
|
export function activate(context) {
|
|
context.subscriptions.push(
|
|
context.api.ui.registerChannelSection('events', {
|
|
label: 'Event Rooms',
|
|
type: 'custom',
|
|
order: 50
|
|
})
|
|
);
|
|
}
|
|
```
|
|
|
|
## Composer Action
|
|
|
|
```js
|
|
export function activate(context) {
|
|
context.subscriptions.push(
|
|
context.api.ui.registerComposerAction('insert-standup', {
|
|
icon: 'ST',
|
|
label: 'Insert standup prompt',
|
|
run: (actionContext) => {
|
|
context.api.messages.send('Standup: yesterday I..., today I..., blocked by...', actionContext.textChannel?.id);
|
|
}
|
|
})
|
|
);
|
|
}
|
|
```
|
|
|
|
Capabilities required: `ui.pages` and `messages.send`.
|
|
|
|
## Profile Action
|
|
|
|
```js
|
|
export function activate(context) {
|
|
context.subscriptions.push(
|
|
context.api.ui.registerProfileAction('wave', {
|
|
label: 'Wave',
|
|
run: (actionContext) => {
|
|
context.api.messages.send(`Waving at ${actionContext.user?.displayName ?? 'someone'}!`);
|
|
}
|
|
})
|
|
);
|
|
}
|
|
```
|
|
|
|
## Toolbar Action
|
|
|
|
Toolbar actions are command-style plugin entries shown in the server side panel's View plugins menu. Use them for small actions that should be easy to launch from a server, such as opening a plugin page, sending a status message, starting a timer, or toggling a plugin feature.
|
|
|
|
The View plugins link appears in `[data-testid="plugin-room-side-panel"]` when the plugin side-panel area is rendered. Opening it shows an overlay menu, positioned like profile-card overlays, with registered actions laid out as plugin icon tiles. The `icon` field can be short text such as `RH`, an emoji, or an image URL; when omitted, MetoYou falls back to initials from the plugin/action labels.
|
|
|
|
Toolbar action callbacks receive an action context with `source: 'toolbarAction'`, the current user, current server, active text channel, and current voice channel when available.
|
|
|
|
```js
|
|
export function activate(context) {
|
|
context.subscriptions.push(
|
|
context.api.ui.registerToolbarAction('open-dashboard', {
|
|
icon: 'RH',
|
|
label: 'Raid Helper',
|
|
run: (actionContext) => {
|
|
context.api.logger.info('Raid Helper opened', {
|
|
channelId: actionContext.textChannel?.id,
|
|
serverId: actionContext.server?.id
|
|
});
|
|
}
|
|
})
|
|
);
|
|
}
|
|
```
|
|
|
|
Capabilities required: `ui.pages`. Add any capability your action uses, such as `messages.send` or `server.read`.
|
|
|
|
Use `registerSidePanel` instead when the plugin needs persistent sidebar content, and use `registerAppPage` when the plugin needs a full-page workflow.
|
|
|
|
## Embed Renderer
|
|
|
|
```js
|
|
export function activate(context) {
|
|
context.subscriptions.push(
|
|
context.api.ui.registerEmbedRenderer('raid-card', {
|
|
embedType: 'raid.card',
|
|
render: (payload) => {
|
|
const card = document.createElement('article');
|
|
const title = document.createElement('h3');
|
|
const body = document.createElement('p');
|
|
|
|
title.textContent = payload?.title ?? 'Raid';
|
|
body.textContent = payload?.description ?? 'No description provided.';
|
|
card.append(title, body);
|
|
return card;
|
|
}
|
|
})
|
|
);
|
|
}
|
|
```
|
|
|
|
Example message content for this embed:
|
|
|
|
```text
|
|
toju:embed:raid.card:{"title":"Friday Raid","description":"Meet in Lobby at 20:00."}
|
|
```
|
|
|
|
## DOM Mount
|
|
|
|
Use DOM mounting only when normal UI contribution points are not enough. `ui.mountElement` resolves its target immediately. If the target does not exist, plugin activation fails with `Plugin mount target not found: <selector>`.
|
|
|
|
Safe uses:
|
|
|
|
- Mounting a global overlay, badge, or modal into `body` during activation.
|
|
- Mounting into a route-specific element only after checking that element exists.
|
|
|
|
Avoid:
|
|
|
|
- Mounting sidebar content into `[data-testid="plugin-room-side-panel"]`. Use `ui.registerSidePanel`.
|
|
- Mounting chat content into `app-chat-messages` during activation without checking for the element.
|
|
|
|
```js
|
|
export function activate(context) {
|
|
const badge = document.createElement('div');
|
|
badge.textContent = 'Raid helper active';
|
|
badge.style.position = 'fixed';
|
|
badge.style.right = '16px';
|
|
badge.style.bottom = '16px';
|
|
badge.style.padding = '8px 10px';
|
|
badge.style.background = '#111827';
|
|
badge.style.color = 'white';
|
|
badge.style.borderRadius = '6px';
|
|
|
|
context.subscriptions.push(
|
|
context.api.ui.mountElement('active-badge', {
|
|
target: 'body',
|
|
position: 'beforeend',
|
|
element: badge
|
|
})
|
|
);
|
|
}
|
|
```
|
|
|
|
Route-specific mount example with a guard:
|
|
|
|
```js
|
|
export function activate(context) {
|
|
const target = document.querySelector('app-chat-messages');
|
|
|
|
if (!target) {
|
|
context.api.logger.warn('Chat messages host is not rendered yet; skipping chat mount');
|
|
return;
|
|
}
|
|
|
|
const banner = document.createElement('div');
|
|
banner.textContent = 'Raid helper active in this chat.';
|
|
|
|
context.subscriptions.push(
|
|
context.api.ui.mountElement('chat-banner', {
|
|
target,
|
|
position: 'afterbegin',
|
|
element: banner
|
|
})
|
|
);
|
|
}
|
|
```
|
|
|
|
The runtime tags plugin-owned DOM and removes it on unload, but plugins should still keep mounts minimal and accessible.
|