Nodes
The nodes a mockup page is made of, and how they read fixtures, link to other pages, nest as sub-pages, and draw sketches, custom pages and sidebar widgets.
A mockup page's tree is a list of nodes. A node is a DMS block, or a sketch for a part no block draws. The page fields around the tree are on Spec file.
Node fields
A node uses the tree format of DmsBlockPreview, the renderer of the block preview page.
| Field | Meaning |
|---|---|
type | A registered block type, such as KpiCard, or sketch. It wins over componentName. |
componentName | The component a registered block type emits, such as dms-kpi-card. |
options | The options the block's component receives. |
children | The nested nodes. A container takes the block types its allowedChildren lists, so a Grid takes only GridRow. Another block takes only the children its block options name. |
id | The id of a child under its parent, unique among its siblings. Comments hold on to it. See Annotations. |
slot | The slot of the parent the child renders in. |
colSpan | The columns a child spans in a grid. |
A block's options are its factory's options, with two differences:
- An option that holds a block, such as a
ChartCard'schart, is a child whoseidis the option's name. - A
Formsection can hold its ownfields, as theFormfactory takes them, or list fields by id infieldIds.
The compiler checks options with ValidateBlockOptions against the block types registered when it reads the spec. A block that an installed module registers works like a built-in one. TableView and ResourceForm follow their own rules, on Controller blocks.
Fixtures
A string option fixture:<key>, at any depth, reads the key <key> of the page's fixtures. The compiler replaces it with the route that answers that value, /api/mockup/<name>/pages/<page>/fixtures/<key>.
{
"type": "ChartCard",
"options": { "title": "Revenue", "fetchUrl": "fixture:revenue", "valueFormat": "currency", "currencyCode": "EUR" },
"children": [{ "id": "chart", "type": "ChartArea", "options": { "xaxisType": "datetime" } }]
}
A key the page does not hold is an issue at the option.
Fixture shapes
A block reads its fixture as it reads its live route's answer. A write checks the fixture each block's fetchUrl names against what that block reads. Each mismatch is a warning in the write's answer, which never refuses the write:
fixture "orders-channel" read by ChartCard at /pages/0/tree/3/children/1: series must be [{ name, data: [{ x, y }] }] or [{ x, y }], got [{"label":"Web","value":928}]
| Block | Fixture shape |
|---|---|
KpiCard | { value, delta?, previousValue?, sparkline?, caption? } |
ChartCard | { value?, delta?, previousValue?, series, comparisonSeries? }. series is [{ name, data: [{ x, y }] }] or [{ x, y }]. |
A chart block, such as ChartArea or ChartDonut | { series }, as for ChartCard |
TopListCard | { items }, each item as the block's staticItems option takes it |
StatGroup, KeyValueList, NavCardGrid, ActivityFeed | { items, count? }, each item as the block's items option takes it |
Meter | { value?, max?, segments?, hint?, valueLabel? } |
Form, ResourceForm | A record object |
A key the block does not read is also a warning. Other blocks are not checked.
A KpiCard or ChartCard fixture with delta or previousValue is a warning when its page has no PeriodSelector. The built card computes its change from the period's comparison, so without one it shows no change. Add a PeriodSelector, or leave both fields out.
Generated fixtures
A fixture can be { "$generate": { "rows"?, "fields" } }. The server then makes up the rows, so the spec states the columns and not the data:
{
"fixtures": {
"customers": {
"$generate": {
"rows": 40,
"fields": {
"_id": "id",
"name": "name",
"email": "email",
"since": "date",
"orders": { "number": [0, 60] },
"spent": { "money": [50, 9000] },
"tier": ["free", "pro", "enterprise"]
}
}
}
}
}
rows is a whole number from 1 to 200, and defaults to 8. fields needs at least one field. Each value of fields is a kind:
| Kind | Value |
|---|---|
"id" | A unique text id: r1, r2 and on. Name the field _id for a table's rowIdKey. |
"name" | A person's first and last name. |
"email" | The email of the row's person, consistent with its name. |
"company" | A company name. |
"city" | A city. |
"text" | A short sentence. |
"date" | An ISO 8601 date and time in the last 30 days, counted back from the start of today in UTC. |
"boolean" | true or false. |
{ "number": [min, max] } | A number from min to max. Whole when both bounds are whole, else rounded to two decimals. |
{ "money": [min, max] } | An amount from min to max, to the cent. |
["a", "b"] | One of the strings, per row. |
The rows are the same on every read. Each value comes from the mockup name, the page id, the fixture key, the field and the row, so adding a field changes no other field. Only date also reads the clock, so dates move forward by one day each day. Everything that reads the fixture sees the generated rows. $generate is the whole fixture value, with no other key beside it.
Page links
A string option page:<id>, at any depth, links to the spec page with that id. It works wherever a block takes a URL or a route, such as a card's to, a row action's target.url or a form's redirectOnSuccess. The compiler replaces it with the viewer's URL of that page, and the Overview draws an arrow between the two pages. A page the spec lacks is an issue.
{
"type": "NavCardGrid",
"options": { "items": [{ "title": "Orders", "icon": "i-ph-shopping-cart", "to": "page:orders" }] }
}
A link to a page with a route passes it a row:
- A link from a
TableViewrow action passes the row's id, read at the table'srowIdKey(_idby default). - A link from a page with a route to one of its own sub-pages with a route passes the same row.
- Any other link passes no row, and the target page shows its sample row.
{
"type": "TableView",
"options": {
"caption": "Orders",
"fetchUrl": "fixture:orders",
"columns": { "customer": { "type": "string" }, "total": { "type": "number" } },
"rowClick": "single",
"rowActions": {
"custom": [
{ "label": "Open", "icon": "i-ph-arrow-right", "isDefault": true, "target": { "type": "page", "url": "page:order" } }
]
}
}
}
The build replaces each page:<id> with the route of the page it builds, such as /orders/{{row._id}} for a row's link to a detail page.
Sub-pages
A page with a parent is a sub-page of that page, such as a list's detail page. A fixture:<key> option that the sub-page does not hold reads the nearest ancestor that holds key.
A sub-page with a route shows one row. A fixture:<key> that names an ancestor's array of rows reads the row whose _id, else id, is the route parameter. The viewer fills the parameter with the row a link passed, else with the first row.
{
"id": "order",
"title": "Order",
"menu": false,
"parent": "orders",
"route": ":id",
"tree": [
{
"type": "ResourceForm",
"options": {
"mode": "view",
"fetchUrl": "fixture:orders",
"fields": [
{ "id": "customer", "label": "Customer", "type": "string" },
{ "id": "total", "label": "Total", "type": "number" }
]
}
}
]
}
The build registers a sub-page under its parent's route, such as orders/:id, and keeps a page with menu: false out of the menu.
Sketches
A sketch draws static HTML and CSS for a part no DMS block draws. The viewer labels it Custom.
{
"type": "sketch",
"options": {
"html": "<ol class=\"steps\"><li>Ordered</li><li>Packed</li></ol>",
"css": ".steps{display:flex;gap:12px}",
"height": 160,
"caption": "Delivery journey"
}
}
| Option | Meaning |
|---|---|
html | Required. The markup, up to 524,288 characters. |
css | The style sheet, up to 524,288 characters. |
height | The frame height in pixels, from 80 to 3,000. Defaults to 320. |
caption | Up to 200 characters. |
states | Named states drawn instead of html. See Named states. |
A sketch has no children and runs no JavaScript. The viewer draws it in a sandboxed <iframe> that runs no script and loads nothing from outside. The compiler checks the markup first and refuses a <script>, an on* handler or a javascript: URL, among others. Sketch check lists the rules. A refused sketch is drawn empty, and each refusal is an issue.
Links to pages
An <a href="page:<id>"> in a sketch links to that spec page, like a block's page link. Only an HTML <a> takes a page link. Any other href is refused, except an #anchor.
A sketch's links work only in Preview. Outside Preview, a click on the sketch selects it. In Preview, a click on the link reloads the viewer on that page.
Named states
states holds other versions of the same part, such as its empty, error or loading state:
{
"type": "sketch",
"options": {
"html": "<ol class=\"steps\"><li>Ordered</li><li>Packed</li></ol>",
"css": ".steps{display:flex;gap:12px}",
"states": {
"empty": "<p>No delivery yet. <a href=\"page:orders\">Pick an order</a></p>",
"error": "<p role=\"alert\">The carrier did not answer.</p>"
}
}
}
- A state name starts with a lowercase letter, then holds lowercase letters, digits and
-, up to 32 characters.defaultis reserved forhtml. - A sketch holds up to 8 states. Each is checked as
htmlis, and drawn with the sketch'scss,heightandcaption.
The inspector of a sketch with states shows a State picker. The pick changes only what the viewer draws, never the spec. A comment pinned while a state is drawn records that state. The build draws each state where the page meets it, such as the empty state when there is no data.
Custom pages
A page with custom: true is one whole-page sketch. The dashboard's top bar, sidebar and page header stay around it. Use it for a page no block arrangement draws, such as a landing page.
{
"id": "board",
"title": "Board",
"icon": "i-ph-kanban",
"custom": true,
"html": "<div class=\"lanes\"><section><h2>To do</h2><a href=\"page:card\">Fix the invoice</a></section></div>",
"css": ".lanes{display:grid;grid-template-columns:repeat(3,1fr);gap:16px}",
"height": 1200,
"states": { "empty": "<p>No card yet.</p>" }
}
| Field | Meaning |
|---|---|
custom | true. false or absent means a page of blocks. |
html | Required. The page's markup, checked as a sketch's. |
css | Optional. Its style sheet. |
height | Optional. The frame height in pixels, from 80 to 3,000. Defaults to 800. |
states | Optional. Its named states. |
tree | Absent or []. A block in it is an issue. |
A comment on a custom page is a comment on the page. Blocks from the catalog cannot be dropped on it.
The build does not copy the sketch. It builds the page as DMS blocks, like every page, and adds a CustomComponent only for a part no block can draw.
Sidebar widgets
sidebar.widgets sketches a widget of the dashboard's sidebar, such as a plan card, that no module provides yet. Each widget appears on every page of the mockup, below the dashboard's own widgets and above the menu.
{
"version": 1,
"sidebar": {
"widgets": [
{
"id": "plan",
"title": "Your plan",
"html": "<div class=\"plan\"><strong>Pro</strong><span>3 of 10 seats left</span></div>",
"css": ".plan{display:flex;flex-direction:column;gap:4px;padding:10px}",
"height": 96
}
]
},
"pages": []
}
| Field | Meaning |
|---|---|
widgets | Required. Up to 10 widgets, drawn in order. |
widgets[].id | Matches ^[a-z0-9][a-z0-9-]{0,63}$. Unique among the widgets. |
widgets[].title | Optional. The caption over the widget, up to 200 characters. |
widgets[].html | Required. The markup, up to 524,288 characters, under the sketch rules. |
widgets[].css | Optional. The style sheet, under the sketch rules. |
widgets[].height | Optional. The frame height in pixels, from 80 to 1,200. Defaults to 120. |
A widget is checked and drawn as a sketch. It cannot be selected, commented or edited in the viewer, so change it in spec.json. The sidebar folded to its icon rail draws no widget.