Targets

Connect fields, rows, buttons, and inputs to views, actions, and lookups.

A target is a typed reference from a part of the interface to an endpoint. It is how a table row opens an edit screen, how a button runs an action, and how a select input reads its options. Targets are the navigation and the interaction of a Backlit app.

This introduction explains why targets use definitions and not URLs, and how to select a target. The page for each target has the full API.

A target takes a definition

resource.view, resource.action, and resource.lookup each return a definition. You pass that definition to the target function, and not a string or a URL.

const orderEdit = orders.view('edit', ['id'], async (ctx, view) => {
  // ...
})

table(rows)
  .setFields(columns)
  .onRowClick(linkTo(orderEdit, (row) => [row.id]))

This has two results. TypeScript reads the params of the definition, so the args of the target must have the correct count and order, and a missing arg is an error when you write the code. And your views contain no URLs, because the host converts the address to a URL. You can rename a view or change the URL structure, and no link breaks.

Args can be an array, or a callback that receives the record. The callback form is for a table or a list, where each row links to its own record.

Select a target

linkTo and visitTo both open a view. The difference is the content. linkTo makes content that exists clickable, such as the value of a field. visitTo creates a control of its own with a text and an icon.

Open a view in a modal or a drawer

A target that opens a view has a mode, which is page, modal, or drawer. The view does not change. The same edit view can open as a page from one screen and as a drawer from a table row, so the user does not leave the list.

visitTo(customerCreate, [], { text: 'Add customer', icon: 'add', mode: 'drawer', primary: true })

A target can also open a view with filters set, such as a link from a dashboard widget to a list that shows only the failed jobs. TypeScript checks the filter names and their values against the filters that the view registers.

Run an action from a button

submitTo is for an action that does not need a full form: archive, approve, or retry. It can run directly, ask for a confirmation in a dialog, or ask for a small set of fields in a dialog.

submitTo(cancelOrder, [order.id], { text: 'Cancel order' }).setDialog({
  title: 'Cancel this order?',
  description: 'This action cannot be undone.',
  submitLabel: 'Cancel order',
})

In a table, the presentation can be a callback that receives the row. Return skip: true to remove the control for one row, such as a “Send confirmation” action that applies to pending subscribers only. skip hides a control and is not an authorization check. The action must still check that the operation is permitted.

Select a record in an input

A form input that selects a related record uses a lookup target. lookupVia creates a picker with a search, and optionsVia creates a closed list. Both name two fields of the lookup: value, which is written to the input, and label, which the input shows. See Lookups for the server side.