TLDR

Events are triggered when something happens on a page, like clicking a button or loading a page.
A list of actions are executed sequentially by a triggered event.
If an action errors, the actions that follow are skipped.
Operators used in action params are evaluated right before the action is executed.
Actions have a skip field that can be used to skip action execution.
The onInit event is triggered the first time a context is mounted and keeps the page in loading until all actions have finished.
The onEnter event is triggered the every time a context is mounted and keeps the page in loading until all actions have finished.
The onInitAsync event is triggered the first time a context is mounted and does not keep the page in loading.
The onEnterAsync event is triggered the every time a context is mounted and does not keep the page in loading.

Blocks can define events which the block can trigger when something happens on the page, like a button being clicked, an input's value being modified or a page being loaded. Some examples are onClick on a Button or onEnter on a PageHeaderMenu block.

Actions are tasks that can be executed, like calling a request, linking to a new page or changing a value in state. An array of actions can be defined for an event defined by a block. If that event gets triggered, those actions will execute sequentially. If any actions error while executing, the actions that follow it won't be executed.

Each action has an id, unique to that action chain, and a type field which are required.

Actions can have a params field for specifying input parameters when executing the action. Operators used in action params will be evaluated right before the action is executed. Some events might have data relating to that event, like what the new value of an input is, or the row that was clicked in a table. The event object can be used in the action using the _event operator.

Actions can also have a skip field. Operators in the skip field are also evaluated before an action is executed, and if the evaluated result is true, that action is skipped and the next action is executed.

Action Schema

The schema for a Lowdefy action is:

id: string: Required - A identifier for the action. It must be unique within the action chain it is defined in.
type: string: Required - The action type to be used. It must be a valid action type.
skip: boolean: The test that determines whether the action will be skipped or not. This is usually written as operators which evaluates to a true or false. Operators are evaluated.
messages: object: Operators are evaluated.
- error: boolean | string: If boolean, whether an error message should be displayed if the action throws an error. Error messages are shown by default. If a string, the error message to show to the user.
- loading: boolean | string: If boolean, whether a loading message should be displayed while the action is executing. Loading messages are not shown by default. If a string, the loading message to show to the user.
- success: boolean | string: If boolean, whether a success message should be displayed if the action completes successfully. Success messages are not shown by default. If a string, the success message to show to the user.
params: object: The input passed to the action. Operators are evaluated.

Events and actions definition example:

- id: block_with_actions
  type: Block
  properties:
    # ...
  events:
    onEvent1:
      - id: action1
        type: ActionType1
        skip:
          # Operator expression that returns true if action should be skipped.
        params:
          # ...
      - id: action2
        type: ActionType2
    onEvent2:
      - id: action3
        type: ActionType3
        params:
          # ...

The event object

When events are triggered, the can provide a data object describing the event (e.g. a description of the clicked item or uploaded file). This data object can be accessed using the _event operator in an action definition.

Context initialisation events

Four events are always defined for context type blocks:

onInit
onEnter
onInitAsync
onEnterAsync

These events can be used to initialise the context or page.

The onInit event is triggered the first time a context is mounted, for example if a page is loaded for the first time. This event blocks page render, in other words, the page will remain in a loading state until all the actions have completed execution. It can be used to set up a context. Actions that take a long time to execute, like Request, should be used sparingly here.

The onEnter event is triggered every time a context is mounted to a page, for example if a user left a page, and returns to it. This event also blocks page render. It can be used to execute actions that should be run each time a page is loaded, like checking if an id is present in the url query parameters, and initialising the state.

The onInitAsync event is triggered the first time a context is mounted, but does not block page render. In other words, the page will not remain in a loading state until all the actions have completed execution. This is a good place to execute non-blocking tasks or requests that might take longer to execute.

The onEnterAsync event is triggered every time a context is mounted, but does not block page render.

Action types

The following actions can be used:

CallMethod - Call a method defined by another block.
Link - Link to another page.
Message - Show a message to the user.
Notification - Show a notification to the user.
Request - Call a request.
Reset - Reset the context.
ScrollTo - Scroll to a point on the page.
SetGlobal - Set a value to the global variable object.
SetState - Set a value to the context state.
Validate - Validate the inputs in the context.

Events and Actions