Appearance
Modules: host calls for tabs, badges and shortcuts
A module's UI bundle gets a host object from register(host) (the front end). Besides the API client, settings and stores, it has three groups of calls that make a module's screens behave like BMA's own: workspace (tabs), menu (badges) and shortcuts (the Shift+? sheet).
The definitions are ModuleHost, ModuleWorkspace, ModuleMenuHost and ModuleShortcutsHost in next-src/src/modules/runtime.ts.
Check before you call
These three groups were added after the first module hosts. A bundle can run on a host that lacks them, so check first and fall back: host.workspace?.open(to) || router.push(to). SAWScore wraps every call this way (appcenter-next/modules/source/sawscore/ui/src/lib/tabs.ts).
Workspace tabs (host.workspace)
to is a route path of the shell, such as /sawscore/applications/42: your ui.routes[].path with its parameters filled in. Every call returns false when to is not a screen of the shell (or is a public one), so you can fall back.
| Call | Does |
|---|---|
open(to): boolean | opens the screen the normal way: its tab if one is open, otherwise a new tab |
openInNewTab(to): boolean | always opens a new tab, even when one for the screen is already open |
replace(to): boolean | shows the screen in the current tab instead; no tab is added (use it for Previous / Next on a record) |
showLinkMenu(event, to): boolean | shows the shell's link menu (Open in a new tab, Open, Copy link) for a contextmenu event, or for Shift+F10 / the menu key. When it returns true, call event.preventDefault() so the browser's own menu stays closed |
useTab() | call it in a component's setup. Returns { id, copy, setTitle(title, subtitle?) } for the tab the screen lives in |
useTab() details:
setTitle('#3 Avery Coleman')names the tab once the record has loaded.nullputs the screen's own title back.copyis 1 for the first tab of a screen, and 2, 3, … for tabs the user duplicated. Keep per-tab state, such as a list's filters, underidorcopy, so two tabs of one list can be filtered differently.
ts
// a record screen, in <script setup>
const tab = host().workspace?.useTab()
watch(record, (r) => tab?.setTitle(r ? `#${r.id} ${r.name}` : null))
function onRowContextMenu(e: MouseEvent, id: number) {
if (host().workspace?.showLinkMenu(e, `/hello/items/${id}`)) e.preventDefault()
}Middle-click and Ctrl / Cmd+click on a link should open a new tab, as in BMA's own screens: call openInNewTab.
Menu badges (host.menu and menu[].badge)
A count on a menu item in the west navigation, such as unread messages. Two ways, often used together:
1. In module.json, name a GET path of your API that answers { "count": <integer> }:
json
"menu": [ { "key": "messages", "title": "Messages", "route": "/hello/messages", "badge": "/hello/messages/unread" } ]- The path must be under one of your
api.prefixes; registration refuses anything else. - The shell asks at most once a minute per module, while someone is signed in and the browser tab is visible.
count0 ornullshows no badge. A 401, 403 or 404 answer stops the asking until the next sign-in, so a user without the permission costs nothing.- Answer from the caller's own data and permissions, and keep it cheap: one indexed count.
2. From a screen, set the number at once when your screen already knows it:
ts
host().menu?.setBadge('messages', unread || null, 'unread')setBadge(menuKey, count, noun?) takes your menu[].key (or its route), the number (null or 0 removes the badge) and a word read out after the number for screen readers ("3 unread", the default noun). It returns false when the key is not one of your module's menu items: a module can't badge another module's menu.
Keyboard shortcuts (host.shortcuts)
Shift+? opens BMA's sheet of keyboard shortcuts. A screen lists its own keys there; it still handles the keys itself (with its own keydown listener). The sheet only documents them.
ts
let off: (() => void) | null = null
onActivated(() => {
off = host().shortcuts?.register(() => [
{ keys: 'N', label: 'New item' },
{ keys: 'Ctrl+S', label: 'Save', group: 'Hello · Item' },
]) ?? null
})
onDeactivated(() => { off?.(); off = null })register(entries)takes a list, or a function that returns the list that applies right now. It returns the function that removes the registration: call it when the screen is left.- Entries belong to the tab that was in front when you registered, and show only while that tab is in front.
groupis the heading on the sheet (default: your module's name). The shell trims long text and keeps a limited number of entries.open()opens the sheet, for a screen's own Keyboard shortcuts button.
Notifications (host.notify)
A screen can put a notification under the bell for the person using it, and read the unread counts. To notify other people, call the platform's notification service from your module's API code instead; see Notifications and messages.
| Call | Does |
|---|---|
post({kind?, title, body?, link?}): Promise<number|null> | adds a notification for the signed-in person; answers its id, or null when it was refused |
unreadCount(): number | unread notifications of the signed-in person |
unreadMessages(): number | unread message threads of the signed-in person |
refresh(): Promise<void> | asks the server for the counts now instead of waiting for the next poll |
kind is info (the default), success, warning or error. link is an in-app route such as /sawscore/messages or an https:// address. A screen can post at most 30 a minute; a notification a screen posts is never e-mailed.
How SAWScore uses them
| Call | Where in appcenter-next/modules/source/sawscore/ |
|---|---|
openInNewTab, replace, showLinkMenu, useTab | ui/src/lib/tabs.ts (helpers used by the application and customer screens) |
menu.setBadge('messages', …, 'unread') | ui/src/lib/talk/inbox.ts |
menu[].badge | module.json: the messages item, "badge": "/sawscore/messages/unread", answered in api/routes_talk.php |
shortcuts.register, shortcuts.open | ui/src/lib/shortcuts.ts |