CMS Interfaces

Quick Actions

Overview

A quick action is a shortcut the backend contributes to the dashboard's command palette: a labelled entry, grouped under a category, that points at a target — a route to navigate to, a table form to open, or an event to emit. Actions are declared once at import time, and each one may name a permission that decides whether a given user is offered it.

Both functions live in @antelopejs-private/cms/interfaces/cms/quick-actions.

Declare a Category and Its Actions

QuickActionCategory(id, info) registers the group; QuickAction(id, info) registers an entry in it. Both return the registered record. Create the category first: registering an action whose category is unknown throws.

import {
  QuickAction,
  QuickActionCategory,
} from "@antelopejs-private/cms/interfaces/cms/quick-actions";

const tasks = QuickActionCategory("tasks", {
  displayName: "$my_app.quick_actions.tasks",
  icon: "i-ph-check-square",
  order: 10,
});

QuickAction("tasks-new", {
  category: tasks,
  displayName: "$my_app.quick_actions.tasks_new",
  icon: "i-ph-plus",
  permission: "pages.tasks.list.table.add",
  target: { type: "navigate", to: "/tasks/new" },
});

Actions are keyed by their category id and their own id, so the same action id may appear under two categories. Registering an id that is already taken keeps the first registration.

`QuickActionCategoryInfo`

Field	Type	Description
`id`	`string`	Category id. Supplied as the first argument of `QuickActionCategory`, not inside `info`.
`displayName`	`string`	Group label. Required.
`icon`	`string`	Icon name.
`order`	`number`	Sort order among categories.

`QuickActionInfo`

Field	Type	Description
`id`	`string`	Action id. Supplied as the first argument of `QuickAction`, not inside `info`.
`category`	`QuickActionCategoryInfo`	The record returned by `QuickActionCategory`. Required.
`displayName`	`string`	Entry label. Required.
`icon`	`string`	Icon name. Required.
`order`	`number`	Sort order within the category.
`permission`	`string`	Permission id the user must hold to be offered the action.
`target`	`QuickActionTarget`	What running the action does. Required.

Access is computed per caller: a platform owner is offered every action, an unauthenticated caller none, and everyone else is offered an action with no permission and, for an action that names one, only when their effective permission set satisfies it (Permissions). That is the same set the sidebar and the route guards use, so an action is never offered where its destination would refuse the caller. Choosing the id of the page or component the action leads to keeps the two in step.

`QuickActionTarget`

type QuickActionTarget =
  | { type: "navigate"; to: string }
  | { type: "openForm"; table: string }
  | { type: "event"; name: string; payload?: unknown };

Variant	Fields	Meaning
`"navigate"`	`to`	Go to a URL.
`"openForm"`	`table`	Open the form of a table.
`"event"`	`name`, `payload`	Emit a named event, with an optional payload.

import {
  QuickAction,
  QuickActionCategory,
} from "@antelopejs-private/cms/interfaces/cms/quick-actions";

const catalog = QuickActionCategory("catalog", {
  displayName: "$my_app.quick_actions.catalog",
  icon: "i-ph-books",
});

QuickAction("catalog-new-book", {
  category: catalog,
  displayName: "$my_app.quick_actions.new_book",
  icon: "i-ph-plus",
  target: { type: "openForm", table: "books" },
});

QuickAction("catalog-refresh", {
  category: catalog,
  displayName: "$my_app.quick_actions.refresh",
  icon: "i-ph-arrows-clockwise",
  target: { type: "event", name: "catalog:refresh", payload: { force: true } },
});

Declare quick actions in a file imported by your module so the registrations run at import time, next to the pages they point at.

Realtime

CMS Auth Documentation