Table events and helpers

These are the parts of a table view that run around its rows: exports, realtime updates, the metadata it registers, the route helpers and its events.

Exports

The export action is offered only when the controller registered all three ExportRoutes. Pressing it starts a background export job, polls its status, and downloads the result; the job machinery itself is shared with any other long export and is documented in Helpers. Which columns land in the file is decided by @Exported.

Realtime

Unless realtime: false is set, a table view registers two realtime topics for its page (and for each generated sub-page), and its routes publish every create, update and delete on the first and track who has a row open on the second. Both are named after the controller's location:

import {
  tableViewPresenceTopic,
  tableViewRowTopic,
} from "@antelopejs/interface-dms/base/table-view";

tableViewRowTopic("/api/orders"); // "tableview:row:/api/orders"
tableViewPresenceTopic("/api/orders"); // "tableview:presence:/api/orders"

The topics are registered with RegisterPageTopic from the table view's onCreated, so they belong to the module whose page it is, as described in Realtime. A module that publishes on a table's row topic itself, such as a background job updating rows, builds the name with tableViewRowTopic rather than spelling out the prefix, and passes the tenant of the rows as tenantId.

The topics are the same for every tenant, but what is published on them is not: the routes publish each change, and each presence, for the tenant the request was made in, so the sessions of the other tenants neither refetch nor see who has a row open. The DMS decides who else receives them, with no option on the table: a table whose rows live in the schema every tenant shares (CORE_SCHEMA_NAME) publishes to every tenant, and a session on a platform page (a module's page) receives the changes of every tenant, as such a page lists the data of all of them. RealtimeMutationContext and RealtimePresenceContext carry the tenant as tenantId, absent on a table of the shared schema.

Two functions let other modules observe those mutations:

import {
  registerRealtimeMutationListener,
  unregisterRealtimeMutationListener,
  type RealtimeMutationContext,
} from "@antelopejs/interface-dms/base/table-view";

const listener = (context: RealtimeMutationContext) => {
  // context.controllerLocation, context.eventType, context.ids, …
};

registerRealtimeMutationListener(listener);

Listeners are additive side observers: they run after the DMS has published the mutation, and a listener that throws is logged, never propagated to the mutating request. A listener is released with the module that registered it, including when that module reloads in development; unregisterRealtimeMutationListener is for a module that stops listening while it stays loaded.

The routes reach the DMS through two interface functions it implements, internal.PublishMutation and internal.AcquirePresence. They are internal: nothing outside the DMS implements them, and the core binds them to each generation of the DMS module, so a mutation made while the DMS reloads waits for the next generation instead of reaching the one being torn down.

Metadata

TableViewMeta is the metadata object the decorators write to and the builder reads from. Retrieve it with GetMetadata(controller, TableViewMeta).

Each entry of config.columns carries id, header, isVisible, type (the serialized data type), accessorKey, listable, enableSorting, enableColumnFilter, defaultValue, accessMode and readonlyBehavior.

Route helpers

table-view also exports the interface functions the wrapped routes call. They are the seam between the interface and its implementation. A consumer wires them by declaring TableViewRoutes, and does not normally call them directly.

Events and functions

CUSTOM_PAGE_FORM_SUCCESS registers { url: string; preserveQuery?: string[] } in WatchFunctionParamMap. The builder uses it itself: the generated new and edit page forms watch FormEvents.SUBMIT_SUCCESS and navigate back to the table, preserving the query parameters named in queryParamFilters. The handler resolves {{params.X}} / {{query.X}} tokens in url against the route being left before navigating; the generated forms rely on it to send the user back to a page whose slug carries parameters: each placeholder of the page's slug becomes the token reading it on the form route (/workspaces/:id becomes /workspaces/{{params.id:1}} from /workspaces/:id/invoiceTable/:id/edit, /workspaces/{{params.id}} from /workspaces/:id/invoiceTable/new). A slug without parameters is used as is. The view form submits nothing and carries no such watch. All three generated pages are registered with FormPageLayout(), the constrained-column layout (Layout and containers).