Actions and Windows¶

An action is what happens when someone presses a Button in your portal. A button can open a window, go to another page, show a notification, or close the window it sits in. A window is portal content that opens over the current page: a dialog in the middle of the screen, or a drawer that slides in from an edge.

A typical use: an orders table with a Details button in each row. Pressing it opens a drawer that shows that order, loaded by its id. This page explains how to build that, and everything else buttons and windows can do.

Actions only run in the portal preview and in the live portal. On the designer canvas a button does nothing when clicked. Test a flow in the preview.

Which widgets run actions¶

Only the Button widget has an action. Tables, data lists and navigation widgets don't.

To act on one row of a table or one item of a list, put a Button inside the row or item. Its action can use the row's values through $record, for example {$record.id}.

A Nav Link is a link, not an action. It has its own Target and behaves like any link on a web page.

Choosing an action¶

Select a Button and open its Action section. The Action field offers five choices:

Open window¶

Pick the window by name. A Window parameters section then lists every parameter the window declares, with one field per parameter. See Passing values to a page or window below.

Navigate to page¶

Pick the page from the list of the portal's pages, or type its route. A route can contain a page parameter, for example /orders/{$params.orderId}, which is filled in when the button is clicked. A Page parameters section then lists every parameter the target page declares.

The route must point to one of this portal's pages. Links to other websites, and routes with ? or # in them, are rejected when clicked. To link to an outside address, use a Nav Link instead.

Show toast¶

A toast is a small message that appears in the corner and goes away on its own.

Close window¶

No settings. It closes the window the button is in, even when the button is nested inside tabs, a list or a table cell. Any windows that were opened underneath stay open.

Passing values to a page or window¶

When you pick a target page or window, the editor lists that target's parameters. Each field takes an expression, and its value is passed to the parameter when the button is clicked. For example, to open a customer window for the customer on the current page:

{$data.customer.id}

The fields follow a few simple rules:

• Each field is labelled with the parameter's label. If the target marks a parameter as required, the field's tooltip says so.
• An expression can read $params, $data, $vars, $portal.state and $user. Inside a table row or list item it can also read $record. See Page and Portal State.
• Put one value in each field, in braces: {$record.id}.
• Leave a field blank to use the target's default. A blank field is not passed at all.
• Changing the target page or window, or switching to another action type, clears every field.

When you navigate to a page, the values go into the address bar, so the reader can bookmark or share the result. Empty values are left out. Only parameters the target page declares are passed. A single value mapped to a parameter that accepts several values becomes a one-item list.

When you open a window, each parameter's value is decided in three steps, with each step overriding the one before:

1. The parameter's default.
2. The values saved with the window's Set Values.
3. The button's expression for that parameter.

An expression that fails or returns nothing leaves the earlier value in place.

Windows¶

Creating a window¶

In the portal editor, open the Content tab of the left panel, choose Add, and under Overlays pick one of:

• Window, a dialog centred on the screen.
• Drawer, a panel that slides in from an edge of the screen.

The new window appears under Overlays in the content list, below the pages. Right-click it to delete it.

A window has no route and no menu entry, so readers cannot reach it by address. A button's Open window action is the only way in.

Window settings¶

Selecting a window opens the Window tab in the ribbon.

If you don't set a size, a modal is 640 by 480 pixels and centred on the screen. A drawer on the left or right edge is 400 pixels wide and full height. A drawer on the top or bottom edge is full width and 400 pixels tall.

Both kinds dim the page behind them. In the editor a drawer is drawn in the middle of the canvas. It is pinned to its edge only in the preview and the live portal.

Window content¶

Each window's content starts with a Window frame: the title bar, the close button and the body. Add widgets to the body as you would on a page. Small widgets such as a badge or a button can go in the title bar.

Don't add a Content Placeholder to a window. Windows don't use layouts.

Data in a window¶

A window has its own parameters and data sources. It doesn't inherit anything from the page underneath. The page's $params and $data are not visible inside the window. The only input a window gets is what the opening button passes in.

The window gets a snapshot when it opens. Later changes on the page behind it don't reach a window that is already open. Closing the window throws away its parameters and data. The page underneath stays as it was.

To send a change from a window back to the page, write it to $portal.state and have the page read it from there.

Stacking windows¶

A button inside a window can open another window. The new one opens on top and the first stays underneath. Each closes on its own.

Good to know¶

• Every window should keep at least one way to close it. Don't turn off the close button, Close on Escape and Close on backdrop click all at once unless a Close window button sits inside the content.
• Deleting a window does not update the buttons that open it. Those buttons fail when clicked until you point them somewhere else. In the editor their action field shows Missing window.
• If a saved action no longer makes sense, for example because it was copied from a place where it doesn't apply, the Action field shows Invalid action — choose a replacement.
• If the editor cannot load a target's parameters, it shows Unable to load page parameters. with a Retry button.

When an action fails¶

A failed action shows a toast titled Action failed with one of these messages: