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.
Action errors can be handled by providing a list of try and catch actions to the event.
Operators used in action params are evaluated right before the action is executed.
The _actions) operator is available for sequential actions to use the values returned from preceding actions in the chain.
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 a event on 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, however, catch actions chain can be defined on a event to trigger when a error in a chain of actions occurs.

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. Some actions also return values which can be passed to preceding actions in the same action chain using the _actions operator.

Actions can also have a skip field. Operators in the skip field will be 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 actions object

When events are triggered, each completed action writes its response to the actions object under the action id object key. Thus all following actions in a event action list have access to the responses of all preceding actions in the same event list through the _actions operator.

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.

Catching action errors

If one action in the chain of event actions fails by throwing an error, the actions in the list following the failed action will not be executed. To handle any errors thrown by an action, Lowdefy event actions can be provided as lists of try and catch actions.

The schema for passing actions to Lowdefy events is:

  (eventName: action[])
  (eventName: {
    try: action[],
    catch?: action[],
  })

Event try catch actions example for dealing with action errors:

- id: block_with_actions
  type: Block
  properties:
    # ...
  events:
    onEvent1:
      try:
        - id: action1
          type: ActionType1
          params:
            # ...
        - id: action2
          type: ActionType2
      catch:
        - id: unsuccessful
          type: ActionType1
          params:
            # ...

Context initialisation events

Four events are always defined for context type blocks, called in the following order:

onInit
onEnter
onInitAsync
onEnterAsync

These events can be used to initialize 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 initializing 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.
JsAction - Call a custom JavaScript function as an action.
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