[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationLive page mockups

Live page mockups

How "Edit as mockup" turns a live page into a mockup, and how mockup_apply_to_page builds the mockup back into that page.

Edit a live page as a mockup

A live page has no builder. A converted page is a mockup like any other. In development, the dashboard header shows Edit as mockup, a pencil before the other dev tools (header action dms-edit-as-mockup, order 89), on every page but /mockup, /mockups, /dms-preview and /branding. It sends the path on screen to POST /api/mockup/from-page and opens the answer's url, /mockup?name=<name>&page=<page>&mode=edit, with Real data on. The MCP tool mockup_from_page does the same from a builder ref.

The conversion reads the page through the builder (GetPageStructure) and writes mockups/<name>/spec.json, named after the page's route (/charts/sales gives charts-sales, / gives home). Every block of the page becomes one node at its place, with its name as id, its slot and its colSpan:

BlockNode
A block the compiler admitsThe block, with the options the builder reads. Options the builder locks, set by code, are left out; the live page keeps them.
An option holding a block, such as a ChartCard's chartA child whose id is the option's name.
An option named *Url (fetchUrl, badgesUrl, submitUrl, at any depth)fixture:<key>, with the fixture null and the route in liveRoutes. One route read by two options is one key.
A TableView bound to a resourceA table over the resource's listed fields, reading made-up sample rows, never the page's rows. Its key in liveRoutes is the resource's list route.
A custom component, a block the builder cannot edit, a value set in code ($ref, $expr, $dataType), an option set in code, unless the block type's own schema files every such option under appearance or layout (those the block draws with its defaults instead; a bound table keeps its columns whatever its options), a route built from the page's parameters or off the site, a block the compiler refusesA Custom sketch that names the block and the blocks under it, captioned with why. When a container refuses a child, such as a Grid holding something other than a GridRow, the container becomes the sketch.

No block is dropped, and the spec has no issue: writeSpec refuses one that has. The answer lists each sketch with the block's builder path and its reason, and the fixture keys Real data reads.

A second click on the same page opens the same mockup and writes nothing. When the page's file changed since, the answer says stale: true, and the dashboard offers Convert again, which converts the page over its mockup page, the spec's other pages kept. A mockup of that name made by hand, or from another page, is never taken: the page gets <name>-2, then -3.

Build it back into the page

The MCP tool mockup_apply_to_page takes { mockup, page } and builds that spec page back into the live page its livePage names. It converts the live page again and pairs each node with the block it stands for: the block named the node's id, or the block name its id gives (see the last row below), among the children of the block its parent stands for, else a block of that name elsewhere on the page that no node there stands for: the one the node still draws first, then one drawn as it is (a sketch or not), then the first in page order. A Custom sketch stands only for a block the page draws as a sketch, so a custom component stays on the page while a sketch of its name is in the mockup. Then it writes the whole block tree with SetPageBlocks in one write, made only if the page is still at livePage.version:

NodeBlock
Unchanged, its slot and span asideKept byte for byte, at the node's place, slot and span.
A Custom sketch standing for the blockKept byte for byte. An edited sketch is also listed.
Options editedWritten. A *Url option reading fixture:<key>, with the key in liveRoutes, gets its route back. A locked option is never written.
A TableView bound to a resourceThe options a mockup draws written, the rest of its options kept.
Moved to another parentWritten new there when the builder can write all of it, else kept where it was.
NoneRemoved.
New, of a block type the builder writesAdded, named after its id. An id the page cannot list a block under, such as revenue-2, _draft or name, gives one it can: revenue_2, block_draft, block_name. A node with no id is named after its type, and the spec records that name as its id.

What only code or data wiring can do is listed in wiring and never written: a fixture standing for no live route, a static* option the live block lacks, a new or edited Custom sketch, a change to a table's columns or rows, an edit to a block held in an option, a move the builder cannot copy, a removed parent kept because a block inside it could not move out (parent), a change to what the page's source locks, a type the builder cannot write there, and a new block whose id gives the block name of another block at its place (name). A slot or span on a top-level block is listed too (placement): the builder lays out the page's top level in order only, so the block is written without it. Each note gives the node's JSON pointer in spec.json and, in kept, the builder path of the live block left as it was. The answer also lists the builder paths it kept, wrote, added and removed, and, in displayName, the page's display name when it wrote the page's title.

When the page changed since the conversion, the tool answers stale and writes nothing. It never creates a page: a page the builder no longer has answers not_found. After the write it records the page's new version in livePage.version, and the name of each new block that had no id as its node's id, so the next apply starts from it and writes nothing new for a mockup it already built.