Skip to main content

Schema based UI

How to define model specs in a realm.

See Model System for the concept overview and the blong-model skill for agent assistance with model development.


Folder Structure​

Each realm that uses the model system organises its models and fixture data in a dedicated folder. The conventional structure (as seen in demo/blong-marine/) is:

marine/
meta/
model/
marineCoralModel.ts ← IModelSpec handler for coral entity
marineFamilyModel.ts
marineHabitatModel.ts
fixture/
marineFixture.ts ← Fixture data handler for Storybook/tests
orchestrator/
marine.ts ← Forwarding orchestrator (dispatches to backend)
browser.ts ← Realm entry point (auto-discovers meta/ folder)

The model files are discovered by the portal orchestrator and mock adapter via the .model handler kind (set by the model() factory). The fixture file is discovered via the .fixture handler kind.


Defining a ModelSpec​

Model specs use the model() factory from @feasibleone/blong. The factory wraps an async handler function whose name follows the pattern {subject}{Object}Model.

// marine/meta/model/marineCoralModel.ts
import {model} from '@feasibleone/blong';

export default model(
() =>
async function marineCoralModel() {
return {
subject: 'marine',
object: 'coral',
objectTitle: 'Coral', // defaults to capitalized 'object'
keyField: 'coralId', // defaults to '${object}Id'

// Browser-side schema overlay (merged with runtime schema from {subject}.{object}.schema handler)
schema: {
properties: {
coral: {
properties: {
coralId: {},
coralName: {title: 'Name', filter: true, sort: true},
familyId: {
title: 'Family',
widget: {type: 'dropdown', dropdown: 'marine.family'},
},
habitatId: {
title: 'Habitat',
widget: {type: 'dropdown', dropdown: 'marine.habitat'},
},
maxDepth: {title: 'Max Depth (m)'},
colorPattern: {title: 'Color Pattern'},
discovered: {widget: {type: 'date'}},
description: {widget: {type: 'textArea'}},
},
// Override table widget options for the browse panel
widget: {
columns: ['coralName', 'familyId', 'maxDepth'],
},
},
},
},

// Named groups of fields for the editor form
cards: {
browse: {
label: 'Coral',
widgets: ['coral'],
},
edit: {
label: 'Coral Details',
widgets: [
'coral.coralName',
'coral.familyId',
'coral.habitatId',
'coral.maxDepth',
'coral.colorPattern',
'coral.discovered',
'coral.description',
],
},
},

// How cards are arranged on the edit page
layouts: {
edit: ['edit'],
},

// Browse page toolbar buttons
browser: {
title: 'Coral List',
icon: 'pi pi-star',
toolbar: [
{
label: 'Create',
icon: 'pi pi-plus',
action: 'component/marine.coral.new',
permission: 'marine.coral.add',
},
{
label: 'Edit',
icon: 'pi pi-pencil',
enabled: 'current' as const,
method: 'component/marine.coral.open',
params: '${current}',
},
{
label: 'Delete',
icon: 'pi pi-trash',
enabled: 'selected' as const,
confirm: 'Delete selected record?',
method: 'marine.coral.remove',
params: {coralId: '${coralId}'},
},
],
},
};
},
);

The aggregator builds the menubar from the specs, so a realm with a handful of models needs no menu code at all: each browse page joins the group named by subjectTitle (the capitalized subject by default). A realm with twenty pages says where each one belongs instead of letting one group grow past the height of a laptop screen:

classifier: true, // reference data a form picks from
menu: {group: 'Registry'}, // a flat group of its own
menu: {group: 'Registry', order: 3}, // …at a chosen position in it
menu: {root: 'Reference', group: 'Sport'}, // nested two levels deep
menu: {title: 'Athletes', icon: 'pi pi-user'}, // leaf label and icon
menu: {hidden: true}, // no entry; still reachable by method

classifier: true is the flag for dropdown sources — sport, discipline, area, category, cycle. Every realm's classifiers land in one Classifiers group with a submenu per realm, so the list a form picks from is found in one place and the realm's own group holds the pages people open all day.

A group title is the merge key: two realms that both declare Registry contribute to one group, and the ids the portal derives from the titles stay language independent. subjectTitle renames a subject's group (Translations for the core dictionary pages).

order fixes a page's position inside its group — lowest first. Pages that name no order come after the ordered ones, alphabetically, so a group where nothing is ordered is simply sorted by label; the comparison uses the English label, because that is what the model declares.

A realm whose menu is written by hand configures ui.portal.portal.menu, which adds groups to the generated ones, and sets menuMode: 'replace' when it should be the whole menubar.


Fixture Data for Storybook and Tests​

The mock adapter auto-generates all CRUD mock handlers from the handlers whose group name ends in .model / .fixture. Create a fixture handler with the ordinary handler() factory from @feasibleone/blong:

// marine/meta/fixture/marineFixture.ts
import {handler} from '@feasibleone/blong';
import marineYaml from '../../data/marine.yaml?raw';

export default handler(
({lib: {yaml}}) =>
async function marineFixture() {
return yaml.parse(marineYaml);
},
);

Not the fixture() factory. fixture() from @feasibleone/blong describes mock OpenAPI documents (a {subjects, dropdowns} shape), so its type rejects the sample-rows object below.

The fixture handler must be named {subject}Fixture and return an object keyed by '{subject}.{object}' with arrays of item objects. The mock adapter calls blong.handler['{subject}Fixture']({}, {}) to load the data.

For inline fixture data (small datasets or when YAML is overkill):

import {handler} from '@feasibleone/blong';

export default handler(
() =>
async function marineFixture() {
return {
'marine.coral': [
{coralId: 1, coralName: 'Brain Coral', familyId: 1, maxDepth: 40},
{coralId: 2, coralName: 'Staghorn Coral', familyId: 2, maxDepth: 25},
],
'marine.family': [
{familyId: 1, familyName: 'Acroporidae'},
{familyId: 2, familyName: 'Faviidae'},
],
};
},
);

The realm's browser.ts must glob the fixture folder next to the models (import.meta.glob(['./meta/model/**/*.ts', './meta/fixture/**/*.ts', …])). The browser platform loads a realm only through the children it is given — it does not scan layer folders the way the server does — so a fixture that browser.ts does not glob never reaches the mock adapter and every story renders empty.

The mock generates the following handlers automatically from each model + fixture:

  • {subject}.{object}.find, .get, .add, .edit, .remove, .report
  • {subject}.{object}.schema — returns {}
  • {subject}.dropdown.list — synthesises from fixture data

Schema Overlay Reference​

Key field properties available in the schema overlay:

PropertyTypeEffect
titlestringOverride field label in forms and column headers
filterbooleanShow field in the browse filter bar
sortbooleanMake column sortable in Explorer
requiredbooleanMark field required (client-side validation)
defaultanyDefault value for new entity forms
widgetIWidgetOverrideWidget type and widget-specific options

Key widget types:

widget.typePrimeReact componentExtra widget props
dropdownDropdowndropdown: 'subject.name'
multiSelectMultiSelectdropdown: 'subject.name'
selectTableDataTable (select)dropdown: 'subject.name'
dateCalendar
dateTimeCalendar (showTime)
textAreaInputTextarea
booleanCheckbox
integerInputNumber (no decimals)
numberInputNumber
currencyInputNumber (currency)currency: 'USD'
selectSelectButtonoptions: [{value, label}]
tableDataTable (editable)widgets: ['col1', 'col2']

Browse Page Configuration​

browser: {
title: 'Corals', // menu item and tab title
icon: 'pi pi-star', // PrimeIcon class
permission: {
browse: 'marine.coral.browse',
add: 'marine.coral.new',
edit: 'marine.coral.open',
delete: 'marine.coral.remove',
},
filter: {isActive: true}, // default filter on page open (optional)
create: [{ // "Create" button override (optional)
title: 'New Coral',
type: 'default',
permission: 'marine.coral.new',
}],
}

What the configuration above produces, captured from demo/blong-marine:

Coral browse page

Species browse page

Habitat browse page

All three are the same generated page: the portal menu and tab, the toolbar, a navigator pane, the table with its search box and paging, and the detail pane that fills in when a row is selected. The Coral picture is filtered to Staghorn by the spec used in the test, which is why it shows one row; Species and Habitat differ only in their IModelSpec. Nothing beyond the spec above draws any of it.

The other half of a model page is the one the pictures do not show — a form nobody wrote either. The create block in the spec above is what the toolbar's Create button runs, and this is the page it opens, live:

Marine/Coral/New — the generated create page, before anything is typedOpen in Storybook

The images are written by demo/blong-marine/test/docs.play.ts, which opens each page and captures it only under BLONG_CAPTURE_DOCS=1; the blong-docs skill documents the conventions for publishing one.


Deletion​

deletion configures what the browse page's Delete button does — prompt (the default), cascade, block or deactivate — and the generated toolbar carries it, so nothing is repeated per button:

deletion: {mode: 'block'}, // refuse, naming the records that still refer to this one
deletion: {mode: 'cascade'}, // take them with it, without asking
deletion: {mode: 'deactivate', flag: {field: 'areaStatus', value: 'inactive'}},

See the deletion pattern for the full reference, what a cascade does to the foreign keys and how to test each mode.


Method Name Overrides​

By default, the model system infers method names from {subject}.{object}.{verb}. To override:

methods: {
find: 'marine.coral.search', // non-standard list method name
report: 'marine.report.coral', // cross-namespace report
}

Adding a Report Page​

report: {
title: 'Coral Report',
permission: 'marine.coral.report',
}

The report page is only registered when this is present. What that produces, beside the browse page it is reached from — a Run Report toolbar button, a params card, and a Results table:

Coral report page

The rows in the picture are the demo database as the suite's own regression specs left it, which is also the honest illustration of one limitation: the params card is not editable, so a generated report cannot be narrowed from its own filter fields yet.