mirror/lowdefy
2
0
Fork 0
mirror of https://github.com/lowdefy/lowdefy.git synced 2025-02-23 14:39:32 +08:00
Code Issues Packages Projects Releases Wiki Activity
a3c698dde6
lowdefy/packages/docs/concepts/events-and-actions.yaml

225 lines
13 KiB
YAML
Raw Blame History

# Copyright 2020-2021 Lowdefy, Inc
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
_ref:
path: templates/general.yaml.njk
vars:
pageId: events-and-actions
pageTitle: Events and Actions
section: Concepts
filePath: concepts/events-and-actions.yaml
content:
- id: md1
type: MarkdownWithCode
properties:
content: |
### 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`](/_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`](/Button) or `onEnter` on a [`PageHeaderMenu`](/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`](/_event) operator. Some actions also return values which can be passed to preceding actions in the same action chain using the [`_actions`](/_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:
```yaml
- 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`](/_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`](/_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:
```yaml
- 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](https://redd.one/blog/debounce-vs-throttle) for a more detailed explanation.
###### Event trailing edge debouncing example:
```yaml
- 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:
```yaml
- 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`](/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](/_url_query), and initializing the [`state`](/context-and-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`](/CallMethod) - Call a method defined by another block.
- [`JsAction`](/JsAction) - Call a custom JavaScript function as an action.
- [`Link`](/Link) - Link to another page.
- [`Message`](/Message) - Show a message to the user.
- [`Notification`](/Notification) - Show a notification to the user.
- [`Request`](/Request) - Call a request.
- [`Reset`](/Reset) - Reset the page validation and `state`.
- [`ScrollTo`](/ScrollTo) - Scroll to a point on the page.
- [`SetGlobal`](/SetGlobal) - Set a value to the `global` variable object.
- [`SetState`](/SetState) - Set a value to the page `state`.
- [`Validate`](/Validate) - Validate the inputs on the page.
- _ref:
path: templates/navigation_buttons.yaml
vars:
previous_page_title: Connections and Requests
previous_page_id: connections-and-requests
next_page_title: Operators
next_page_id: operators
Reference in New Issue View Git Blame Copy Permalink