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.
Actions that are async: true will not executed sequentially nor stop the event if they error.
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.

All blocks implements onMount and onMountAsync events. These are useful for triggering actions when a block is mounted. For the onMount event, the block only mounts when the event action chain is completed, however, for the onMountAsync event, the block will mount as soon as possible while the event actions completes execution.

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 an error in a chain of actions occurs.

Actions which are async: true are an exception to the sequential rule of the actions chain. These actions will be executed asynchronously and the next actions in the chain will not wait for them to finish. If any async: true action throws an error, the chain will not be stopped and the event will still be completed successfully.

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.
async: boolean: This determines whether the action will be evaluated asynchronously. Operators are not evaluated on async.
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.

The schema for passing actions to Lowdefy events is:

  (eventName: action[])
  (eventName: {
    debounce?: {
      ms?: number,
      immediate?: boolean,
    },
    try: action[],
    catch?: action[],
  })

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.

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:
            # ...

Debouncing events

Event debouncing can be turned on by setting the debounce field on event objects. If debounce.immediate is true, leading edge debouncing or throttling will apply, else it will be debounced as trailing edge.

To control the debounce delay, set debounce.ms to the number of milliseconds to delay. The default delay is 300 milliseconds. If an event is triggered within that time, the event will not be triggered again. See debounce vs throttling for a more detailed explanation.

Event trailing edge debouncing example:

- id: block_with_actions
  type: Block
  properties:
    # ...
  events:
    onEvent1:
      debounce:
        ms: 1000
      try:
        - id: action1
          type: ActionType1
          params:
            # ...
        - id: action2
          type: ActionType2

Event throttling or leading edge debouncing example:

- id: block_with_actions
  type: Block
  properties:
    # ...
  events:
    onEvent1:
      debounce:
        ms: 1000
        immediate: true
      try:
        - id: action1
          type: ActionType1
          params:
            # ...
        - id: action2
          type: ActionType2

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 page validation and state.
ScrollTo - Scroll to a point on the page.
SetGlobal - Set a value to the global variable object.
SetState - Set a value to the page state.
Validate - Validate the inputs on the page.

Events and Actions