Skip to content
ReferenceForDeveloper

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.

CallDoes
open(to): booleanopens the screen the normal way: its tab if one is open, otherwise a new tab
openInNewTab(to): booleanalways opens a new tab, even when one for the screen is already open
replace(to): booleanshows the screen in the current tab instead; no tab is added (use it for Previous / Next on a record)
showLinkMenu(event, to): booleanshows 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. null puts the screen's own title back.
  • copy is 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, under id or copy, 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.

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.
  • count 0 or null shows 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.
  • group is 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.

CallDoes
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(): numberunread notifications of the signed-in person
unreadMessages(): numberunread 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 ​

CallWhere in appcenter-next/modules/source/sawscore/
openInNewTab, replace, showLinkMenu, useTabui/src/lib/tabs.ts (helpers used by the application and customer screens)
menu.setBadge('messages', …, 'unread')ui/src/lib/talk/inbox.ts
menu[].badgemodule.json: the messages item, "badge": "/sawscore/messages/unread", answered in api/routes_talk.php
shortcuts.register, shortcuts.openui/src/lib/shortcuts.ts