[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationController blocks

Controller blocks

How a mockup builds TableView and ResourceForm from fixtures, with their forms, archive mode, column displays, boards and views, and how it reads live routes.

In code, TableView and ResourceForm take a controller class. A mockup has no controller, so it builds both blocks from fixtures. Any other block type that needs a controller is an issue, and the viewer draws it as a block that needs a backend.

Tables

A mockup table takes the options of TableView.fromSource:

OptionMeaning
captionRequired. The title above the rows. A table without a caption is an issue, except on a page converted from a live page, whose tables mirror that page's own.
fetchUrlfixture:<key>, naming an array of row objects.
columnsKeyed by row field. Each column takes type, a data type id such as string, number, date, boolean or select. Optional keys are name, description, order, isVisible, filterable, sortable, cellWrap, size, display and group.
capabilitiesDefaults to search, sort, paginate and filter, all on. Tabs, quick filters and queryParamFilters need filter: true.

The compiler builds the table with the real TableView.fromSource. The table reads its rows from the fixture's rows route, which applies search, sort, pagination and every filter the table sends. Tabs, quick filters, views and column filters therefore narrow the fixture's rows as they would narrow real data. See the rows route on HTTP API.

json
{
  "type": "TableView",
  "options": {
    "caption": "Orders",
    "fetchUrl": "fixture:orders",
    "columns": { "customer": { "name": "Customer", "type": "string" }, "total": { "name": "Total", "type": "number" } },
    "rowActions": { "details": true },
    "formContainer": { "type": "drawer" }
  }
}

Add, edit and details forms

A mockup table is read-only unless its spec turns on rowActions.add, rowActions.edit or rowActions.details. Each takes true or a row action config, such as { "rule": { "field": "status", "equals": "draft" } }. An action left out is off. The real TableView reads an absent action as on, so the build turns off what the mockup leaves out.

formContainer says where each form opens:

formContainerForms open in
{ "type": "modal", "size"?, "pages"? }A modal. The default.
{ "type": "drawer", "direction"?, "pages"? }A drawer from the bottom, or from the right with "direction": "right".
{ "type": "page", "pages"? }A page of their own. See below.

The forms are generated over the table's columns, as the real TableView generates them. Saving a form answers the row but keeps nothing, so the table's rows do not change. The details form draws every field read-only. pages.new, pages.edit and pages.details set each form's { displayName?, description? }.

With "type": "page", each form opens on a page, in one of two ways. Each form of a table picks its own.

  • A generated page. The default. Leave the form's pages entry out, or give it only a displayName and a description. The mockup adds a hidden sub-page that holds the generated form. Write no spec page for it.
  • A custom page. For a form or a detail view that no generated form draws. Give the form { "urlSlug": "page:<id>", "customPage": true }, and write the spec page it names. The edit and details pages show one row, so they need a route.
json
{
  "pages": [
    {
      "id": "orders",
      "title": "Orders",
      "fixtures": { "orders": [{ "_id": "o1", "customer": "Acme", "total": 120 }] },
      "tree": [
        {
          "type": "TableView",
          "options": {
            "caption": "Orders",
            "fetchUrl": "fixture:orders",
            "columns": { "customer": { "type": "string" }, "total": { "type": "number" } },
            "rowActions": { "edit": true, "details": true },
            "formContainer": {
              "type": "page",
              "pages": {
                "edit": { "urlSlug": "page:order-edit", "customPage": true },
                "details": { "urlSlug": "page:order", "customPage": true }
              }
            }
          }
        }
      ]
    },
    { "id": "order-edit", "title": "Edit order", "menu": false, "parent": "orders", "route": ":id", "tree": [] },
    { "id": "order", "title": "Order", "menu": false, "parent": "orders", "route": ":id", "tree": [] }
  ]
}

Prefer the default details view in a modal or a drawer. A details page earns its place only when it adds something to the row's fields, such as KPIs or related lists.

On a table's details page, a ResourceForm must be in view mode. On its edit page, it must not be. A form in the wrong mode is an issue at its options/mode.

The build replaces each page:<id> slug with the slug of the page it builds, relative to the table's page: new, :id/edit or :id.

Archive mode

"archiveMode": true draws the table as the real TableView draws one whose controller has an @ArchiveField:

  • A Show archived toggle above the rows.
  • Archive in the row menu of an active row, and Restore in the row menu of an archived one.
  • Edit, when rowActions.edit is on, only on active rows.

A row is archived when its isArchived field is true. When the fixture's rows have no isArchived, the mockup archives the last quarter of them, at least one and never all. archivedCountLabel is the caption's count while archived rows show, with {count} for their number.

json
{
  "type": "TableView",
  "options": {
    "caption": "Orders",
    "fetchUrl": "fixture:orders",
    "columns": { "customer": { "name": "Customer", "type": "string" } },
    "archiveMode": true,
    "archivedCountLabel": "{count} archived orders"
  }
}

rowActions.archive: false or rowActions.restore: false turns one action off. A table that turns either on without archiveMode is an issue.

Form groups

The generated forms group their fields as the real TableView groups them from @Column({ group }) and @ColumnGroup(id, config). A column's group names its group. The table's columnGroups describes each group as { label, description?, orientation?, order? }.

json
{
  "type": "TableView",
  "options": {
    "caption": "Customers",
    "fetchUrl": "fixture:customers",
    "columns": {
      "name": { "name": "Name", "type": "string", "order": 1 },
      "email": { "name": "Email", "type": "string", "order": 2, "group": "contact" },
      "phone": { "name": "Phone", "type": "string", "order": 3, "group": "contact" }
    },
    "columnGroups": { "contact": { "label": "Contact", "orientation": "horizontal" } },
    "rowActions": { "add": true, "edit": true, "details": true }
  }
}

A group's fields gather where its first column stands. A group that columnGroups does not declare takes its id as its title.

Column displays

A column's display takes one of two shapes.

The first is the shape the builder proposes for a mapped database column, so a proposal goes into a spec as it is:

kindColumn typeMeaning
badgestring or selectitems lists the values as { value, label, tone }. tone is one of neutral, primary, secondary, success, warning, error and info. The cells draw as pills.
pricenumber or pricecurrency is an optional ISO 4217 code, such as EUR. The cells draw as amounts.
json
{
  "status": {
    "type": "string",
    "filterable": true,
    "display": {
      "kind": "badge",
      "items": [
        { "value": "paid", "label": "Paid", "tone": "success" },
        { "value": "pending", "label": "Pending", "tone": "warning" }
      ]
    }
  },
  "total": { "type": "number", "display": { "kind": "price", "currency": "EUR" } }
}

The second is a cell display of TableView, as { type, options? }. type is one of identity, pills, relative_date, indicator, status_pill, two_line, progress, sparkline, duration, bytes, string and mono. options are the options of its class, such as an identity cell's avatarField.

json
{ "customer": { "type": "string", "display": { "type": "identity", "options": { "avatarField": "avatar", "subtitleField": "email" } } } }

The compiler checks both shapes as the builder does. An unknown display, an option its class does not take, or a badge on a date column is an issue. Because the checks match, the agent can send a column's display, group, isVisible, size, cellWrap and description to builder_add_field or builder_configure_field as the spec writes them. See Column presentation.

Board, groups, tabs and views

A mockup table also takes these options of the real TableView:

OptionMeaning
kanban{ groupByField, draggable?, columnMaxHeight? }. A board with one column of cards per value of groupByField, a select, boolean or status column. Cards never move in a mockup.
grouped{ groupByField, by?, collapsible?, count? }. The grid with a header row per group. by is value, day or week. day and week need a date column.
tabsFrom{ column }. Tabs read from a badge column: "All", then one tab per badge item, in its tone. The column must be filterable. Leave tabs out when you use it.
tabsThe tabs of a TableView. A tab takes id, label, filter, icon, textColor, iconColor, to, permission, permissionId, countFrom and navBadge. Another key is an issue.
views{ items, layout?, defaultView?, userViews? }. Saved views. A view is { id, label, icon?, tone?, dot?, count?, filters?, search?, sort?, columns?, display?, density? }.
json
{
  "type": "TableView",
  "options": {
    "caption": "Orders",
    "fetchUrl": "fixture:orders",
    "labelKey": "customer",
    "columns": {
      "customer": { "type": "string", "sortable": true },
      "status": {
        "type": "string",
        "filterable": true,
        "display": { "kind": "badge", "items": [{ "value": "paid", "label": "Paid", "tone": "success" }] }
      },
      "total": { "type": "number", "sortable": true }
    },
    "tabsFrom": { "column": "status" },
    "kanban": { "groupByField": "status" },
    "views": { "items": [{ "id": "large", "label": "Large orders", "sort": [{ "field": "total", "desc": true }] }] }
  }
}

The board and the grouped display join the table's displays, so defaultDisplay, mobileDisplay and a view's display can name them. builder_map_resources takes the same settings in its tableOptions, under its own names: kanban.groupBy and grouped.groupBy instead of groupByField, and column instead of a view filter's accessorKey or a sort's field.

Resource forms

A mockup ResourceForm takes a serialized form:

OptionMeaning
fetchUrlfixture:<key>, naming the record object.
fieldsThe form's fields, as a Form takes them.
sections, sectionNavOptional. Titled cards of fields and groups, as the real Form takes them. sectionNav is side, jump or none.
modenew, edit or view. In view mode every field is read-only, as in the real details view.

A mockup form has no submitUrl. The compiler validates it as a Form.

json
{
  "type": "ResourceForm",
  "options": {
    "mode": "view",
    "fetchUrl": "fixture:customers",
    "sectionNav": "jump",
    "sections": [
      { "id": "general", "label": "General", "icon": "i-ph-identification-card", "fields": [{ "id": "name", "label": "Name", "type": "string" }] },
      { "id": "notes", "label": "Notes", "fields": [{ "id": "notes", "label": "Notes", "type": "string" }] }
    ]
  }
}

Live routes

A page's liveRoutes maps a fixture key to the route of your running app that answers the same data:

json
{
  "id": "sales",
  "title": "Sales",
  "liveRoutes": { "api-sales": "/api/sales" },
  "fixtures": { "api-sales": null },
  "tree": [{ "id": "sales", "type": "ChartCard", "options": { "title": "Sales", "fetchUrl": "fixture:api-sales" } }]
}

The compiler then compiles the page twice. tree reads the fixtures, and realTree reads each mapped key from its route. The viewer's Real data switch picks one. A table's live route must answer { results, total }, as a list route does. Issues come from the fixture side only.

With Real data off, the page calls no route of your app:

  • A fixture:<key> reads its fixture.
  • Any other URL a block would request or load, such as a fetchUrl, an image src or a location, is replaced with a route that answers an error. The block shows its error state.
  • A Content Security Policy keeps the page's images, media and requests on the mockup's own routes and the dashboard's assets. An image cell that holds an outside URL does not load.