Actions component

An action is a clickable button or icon that runs an action on a component, runs a system action, navigates to another location, or sends an HTTP request.

A dark toolbar with an ON switch on the left and three icon buttons beside it. — Actions component showing interactive buttons for system controls and navigation

Use an action for system controls, navigation buttons, data refresh and other commands that the user starts with a click. Use a Toggle for a switch that alternates between two states.

Parameters

Parameter	Type	Required	Default	Description
`class`	string	No	None	CSS classes applied to the button or icon
`label`	string	No	None	Caption of the button, also used as the title of the confirmation dialog and as the caption of the progress bar
`image`	string	No	None	Icon name, for example `Renew` or `Settings`, shown on `icon` and `button` actions. An icon filename such as `nav_battery_active.svg` is also accepted. Refer to Icon component for how to find icon names
`imageAlt`	string	No	None	Accessible label for the icon
`mode`	string	Yes	None	Display mode, one of `icon`, `button` or `auto`. `auto` displays a button when `label` is set and an icon otherwise
`invoke`	string	No	`Component`	How a click is carried out, one of `Component`, `System`, `Endpoint` or `Navigate`. Refer to Invoke types
`actionId`	string	Conditional	None	Name of the action to run. Required when `invoke` is `Component` or `System`. Refer to Action names
`target`	string	Conditional	None	Location to navigate to. Required when `invoke` is `Navigate`
`endpointAction`	object	Conditional	None	Details of the HTTP request. Required when `invoke` is `Endpoint`. Refer to Endpoint action parameters
`value`	object	No	None	Payload posted with the action request
`trackProgress`	boolean	No	`false`	Shows a progress bar and polls the progress of the action while it runs
`confirmMessage`	string	No	None	Message of a confirmation dialog that the user must accept before the action runs
`restartingOnSuccess`	boolean	No	`false`	After the action succeeds, shows a wait dialog and polls until the Profinity engine is running again. Use the parameter for actions that restart the engine
`enabled`	boolean	No	`true`	Whether the button can be clicked. The state can be bound with the `enabled` target
`bind`	array	No	None	Data binding. The `enabled` target sets whether the button can be clicked, the `tooltip` target sets its hover text, and the `classes` target adds CSS classes to it.

id, hyperlink, openHyperLinkInNewWindow, and visible are accepted but have no effect. To navigate, use invoke: Navigate with target. To control the visibility of an action, use a binding on the component that contains the action.

In auto mode the label decides the display, so an action with a label is displayed as a button and an action without a label is displayed as an icon. An image value that matches no known icon is loaded as an image file from the /Profile/Images directory.

Invoke types

The regions, icons, and buttons of an Image or 3D model component, and a Toggle, use the same invoke types through an action invocation object. Refer to Action invocation for its parameters.

Invoke	Behaviour
`Component`	Runs the action named by `actionId` on the component that owns the dashboard, and posts `value` with the request. This is the default
`System`	Runs the system-level action named by `actionId` on the Profinity engine. The available system actions are `UPDATE PROFINITY`, `INSTALL PROFINITY` and `RESTART PROFINITY`
`Navigate`	Navigates the web interface to `target`, entirely in the browser
`Endpoint`	Describes an HTTP request in `endpointAction`. The browser sends the request, on an action button or on a region, icon, or button of an Image or 3D model component

Endpoint action parameters

Parameter	Type	Required	Default	Description
`method`	string	Yes	None	HTTP method of the request
`url`	string	Yes	None	Relative or absolute address that the request is sent to
`label`	string	No	None	Caption of the button for the request
`description`	string	No	None	Supporting text beside the button
`image`	string	No	None	Icon name shown on the button
`imageAlt`	string	No	None	Accessible label for the icon
`confirmMessage`	string	No	None	Message of a confirmation dialog shown before the request is sent
`successKinds`	array of string	No	None	What the interface does after the request succeeds. `Toast` shows the response message, or `Action completed.` when the response has no message. On a dashboard only `Toast` has an effect. `ReloadSettings`, `ShowServiceAccountTokenDialog` and `RefreshOnClose` apply on settings pages only

Endpoint actions run from the browser. The browser sends the HTTP request itself, with the signed-in user's credentials. An action button with invoke: Endpoint therefore works the same way as an Endpoint on a region, icon, or button of an Image or 3D model component. If the request fails, the browser shows an error message with the reason.

Examples

Enter the examples in the YAML tab of the dashboard editor, as described in Build a dashboard. Each example starts with a dashboard: key, so pasting one replaces the whole dashboard in the YAML tab.

A button with a label and an icon:

dashboard:
  items:
    - row:
        items:
          - action:
              label: "Refresh Data"
              mode: "button"
              invoke: Component
              actionId: "Refresh"
              image: "Renew"
              imageAlt: "Refresh"

Icon only:

dashboard:
  items:
    - row:
        items:
          - action:
              mode: "icon"
              invoke: Component
              actionId: "Settings"
              image: "Settings"
              imageAlt: "Settings"

A system action with a confirmation dialog that waits for the engine to restart:

dashboard:
  items:
    - row:
        items:
          - action:
              label: "Restart Profinity"
              mode: "button"
              invoke: System
              actionId: "RESTART PROFINITY"
              confirmMessage: "Restart Profinity now?"
              restartingOnSuccess: true

A long-running action with a progress bar:

dashboard:
  items:
    - row:
        items:
          - action:
              label: "Update Firmware"
              mode: "button"
              invoke: Component
              actionId: "Update Firmware"
              trackProgress: true
              confirmMessage: "Update the firmware now?"

A button that navigates to another location:

dashboard:
  items:
    - row:
        items:
          - action:
              label: "View Battery Pack"
              mode: "button"
              invoke: Navigate
              target: "/component?componentId=Battery%20Pack"

Action names

A Component action runs one of the actions that the component named by the dashboard offers. The Actions API lists those names at /api/v2/Actions/{componentId}. The examples on this page use Refresh and Settings to show the syntax, and no shipped component offers those names, so use a name from that list. A System action runs one of UPDATE PROFINITY, INSTALL PROFINITY or RESTART PROFINITY. A System action with any other name is rejected with the message "No system action of that id was found".

Component and System actions need the Allow component actions permission. Firmware actions are the actions a component lists for its firmware, such as updating firmware or its settings. A custom component can define its own. Firmware actions need Allow firmware actions. A user without the permission is refused: the request fails, the browser shows the API error, and the action does not run.