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

feat(docs): Update events-and-actions.

Browse Source
This commit is contained in:
Gervwyk 2021-01-25 10:15:26 +02:00
parent d6b0081099
commit a09bb114f3
3 changed files with 112 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
packages/docs/concepts/actions.yaml
View File

@ -1,95 +0,0 @@
# 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: actions
pageTitle: Actions
section: Concepts
content:
- id: md1
type: Markdown
style:
'.markdown-body':
fontSize: 14px
properties:
content: |
`Actions` can be used to perform actions, like calling requests or linking to a new page, based on events in your app, like button clicks or page loads.
Each block defines the events for which it will call actions. The actions to be executed can be defined as a list of action definitions, under that event's name in the actions object of a block. The event names usually start with the keyword "on", like `onClick`, `onChange`, or `onInit`. Each action definition has an `id` (which should be unique in that action chain), a `type`, and a `params` object, which has the parameters that specify how the action should execute.
###### Actions definition example:
```yaml
- id: block_with_actions
type: Block
properties:
# ...
actions:
onEvent1:
- id: action1
type: ActionType1
params:
# ...
- id: action2
type: ActionType2
params:
# ...
onEvent2:
- id: action3
type: ActionType3
params:
# ...
```
# Context initialisation actions
Four action events are always defined for [`context`](/context) type blocks:
- `onInit`
- `onEnter`
- `onInitAsync`
- `onEnterAsync`
These actions can be used to initialise the context or page.
The `onInit` action will execute the first time a context is create (for example if a page is loaded for the first time), before anything is rendered. 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` action will execute every time a context is rendered again (for example if a user left a page, and returns to it), also before anything is rendered to the screen. 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 based on that.
The `onInitAsync` action will execute the first time a context is created, but after rendering has started. This is a good place to execute requests that might take longer to execute.
The `onEnterAsync` action also executes after renderering starts, and executes every time a context is rendered.
# Action types
The following actions can be used:
- [`CallMethod`](/CallMethod) - Call a method defined by another block.
- [`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 context.
- [`ScrollTo`](/ScrollTo) - Scroll to a point on the page.
- [`SetGlobal`](/SetGlobal) - Set a value to the global object.
- [`SetState`](/SetState) - Set a value to the state.
- [`Validate`](/Validate) - Validate the inputs in the context.s
- _ref:
path: templates/navigation_buttons.yaml
vars:
previous_page_title: Context
previous_page_id: context
next_page_title: Connections
next_page_id: connections

108
packages/docs/concepts/events-and-actions.yaml Normal file
View File

@ -0,0 +1,108 @@
# 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
content:
- id: md1
type: Markdown
style:
'.markdown-body':
fontSize: 14px
properties:
content: |
### TDLR;
- A list of actions are executed sequentially by a triggered events.
- Events are triggered when something happens on a page, like clicking a button or loading a page.
- Operators used in action `params` are evaluated right before the action is executed.
- `onInit` is triggered the first time a context is mounted and keeps the page in loading for all actions to finish.
- `onEnter` is triggered the every time a context is mounted and keeps the page in loading for all actions to finish.
- `onInitAsync` is triggered the first time a context is mounted and does not keeps the page in loading.
- `onEnterAsync` is triggered the every time a context is mounted and does not keeps the page in loading.
-----------
Events triggered on a page will fire a list of actions. Blocks has predefined events for which it will call actions, like `onClick` on a [`Button`](/Button) or `onEnter` on a [`PageHeaderMenu`](/PageHeaderMenu) block.
By defining a list of action to execute when a given event is triggered, a chain of tasks can be completed sequentially, like calling a request when a page is opened, or linking to a page when a button is clicked.
Each action has an `id`, unique to that action chain, a `type`, and 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.
###### Events and actions definition example:
```yaml
- id: block_with_actions
type: Block
properties:
# ...
events:
onEvent1:
- id: action1
type: ActionType1
params:
# ...
- id: action2
type: ActionType2
params:
# ...
onEvent2:
- id: action3
type: ActionType3
params:
# ...
```
# Context initialisation events
Four events are always defined for [`context`](/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](/_url_query), and initialising 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.
- [`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 context.
- [`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 context `state`.
- [`Validate`](/Validate) - Validate the inputs in the context.
- _ref:
path: templates/navigation_buttons.yaml
vars:
previous_page_title: Context
previous_page_id: context
next_page_title: Connections
next_page_id: connections

8
packages/docs/lowdefy.yaml
View File

@ -90,11 +90,11 @@ menus:
pageId: context-and-state
properties:
title: Context and State
- id: actions
- id: events-and-actions
type: MenuLink
pageId: actions
pageId: events-and-actions
properties:
title: Actions
title: Events and Actions
- id: connections
type: MenuLink
pageId: connections
@ -244,7 +244,7 @@ pages:
- _ref: tutorial/next-steps.yaml
- _ref: concepts/context-and-state.yaml
- _ref: concepts/actions.yaml
- _ref: concepts/events-and-actions.yaml
- _ref: concepts/connections.yaml
- _ref: concepts/layout.yaml
- _ref: concepts/operators.yaml