Appearance
Modules: the front end
A module's screens are one JavaScript bundle (ui.bundle, usually dist/index.js), built from ui/src/index.ts. BMA loads it from the API after sign-in for organizations that have the module enabled, checks its id and version, and calls register() once.
register()
ts
export const id = __MODULE_ID__ // filled in by the build from module.json
export const version = __MODULE_VERSION__
export function register(h: Host) {
setHost(h)
return {
routes: [], // extra screens, mounted under /m/<id>/…
components: { Hello: HelloView }, // the names module.json's ui.routes[].component use
widgets: {}, // components for App Builder widgets (ui.widgets)
}
}Screens and menu items
json
"ui": { "bundle": "dist/index.js", "routes": [ { "path": "/hello", "component": "Hello", "title": "Hello", "permission": "hello.view" } ] },
"menu": [ { "key": "main", "title": "Hello", "route": "/hello", "parent": null, "permission": "hello.view" } ]A menu item's route must be one of your ui.routes. parent is another of your items' key, null for the top level, or folder:<slug> for one of BMA's folders. /admin/…, /login and /store are reserved.
What the host gives you
host() | |
|---|---|
api | BMA's HTTP client: signed-in session, CSRF token and the API address already set; api.get('/hello/hello') |
settings | your module's non-secret settings for this organization |
stores | the signed-in user (auth), app settings, view state |
components | BMA's own building blocks: QueueGridPanel, DocumentPane, GenericQueueView, ModuleBorderFrame |
router, module | the router, and your id and version |
apiBase | the API address, for building links to your API paths (downloads) |
workspace | open screens in tabs, replace the current tab, the link menu, name your tab: host calls |
menu | setBadge(): a count on one of your menu items: host calls |
shortcuts | list your screen's keys on the Shift+? sheet: host calls |
workspace, menu and shortcuts are newer than the rest: check they exist before you call them.
Shared libraries come from BMA, so don't bundle your own copy: vue, vue-router, pinia, vuetify (its components are available as <v-…> without imports), axios, ag-grid-community, ag-grid-vue3. Never import BMA's internals (@/…): the build refuses it.
Building
ui/vite.config.ts is plain data: export default { entry: 'src/index.ts', bundle: 'dist/index.js' }. Build with bin/build-modules.sh <install copy> (it also stamps checksums), or only build with cd next-src && npx tsx scripts/build-modules.ts --out-root=<dir> <id>. CSS is bundled into the JS.
After a new version is enabled, users get it on their next sign-in or reload. A tab opened before the upgrade asks for the old version; reload it.