@lowdefy/docs 3.23.2 → 4.0.0-alpha.10

package/concepts/events-and-actions.yaml

@@ -1,224 +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: 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

package/concepts/hosting-files.yaml

@@ -1,50 +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: hosting-files
-    pageTitle: Hosting Files
-    section: Concepts
-    filePath: concepts/hosting-files.yaml
-    content:
-      - id: md1
-        type: Markdown
-        properties:
-          content: |
-            A Lowdefy app provides a convenient method to host __public__ files under the `/public/*` app route. Add content to be hosted publicly by creating a folder named `public` in the root of a Lowdefy project folder, next to the `lowdefy.yaml` file. Place the public content in this folder to host this content with your app.
-
-            All content in this folder will be publicly accessible at `{{ APP_URL }}/public/{{ FILE_PATH_NAME }}`. For example, the logo at the top of this page is hosted at [`https://docs.lowdefy.com/public/logo-light-theme.png`](http://localhost:3000/public/logo-light-theme.png). Sub-folders inside the public folder are supported.
-
-            By default, the `public` folder of a Lowdefy app will serve some files which most apps need:
-            - `apple-touch-icon.png`: A 180x180px png image file to be used as the apple PWA icon.
-            - `icon-32.png`: A 32x32px png image file to be used as fallback favicon for some browsers.
-            - `icon-512.png`: A 512x512px png image icon.
-            - `icon.svg`: A svg image file which will be used as favicon if supported by browser.
-            - `logo-dark-theme.png`: A ~250x72px png image used as the header image for [`PageHeaderMenu`](/PageHeaderMenu) and [`PageSiderMenu`](/PageSiderMenu) blocks on desktop when the block theme is set to `dark`.
-            - `logo-light-theme.png`: A ~250x72px png image used as the header image for `PageHeaderMenu` and `PageSiderMenu` blocks on desktop when the block theme is set to `light`.
-            - `logo-square-dark-theme.png`: A ~125x125px png image used as the header image for `PageHeaderMenu` and `PageSiderMenu` blocks on mobile when the block theme is set to `dark`.
-            - `logo-square-light-theme.png`: A ~125x125px png image used as the header image for `PageHeaderMenu` and `PageSiderMenu` blocks on mobile when the block theme is set to `light`.
-            - `manifest.webmanifest`: The app [web manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest).
-
-            Any of these files can be overwritten by replacing the file with a modified version. For example, to replace the logo inside the header of `PageSiderMenu` on all pages, add a ~250x72px logo inside the project folder at `/public/logo-light-theme.png`.
-
-      - _ref:
-          path: templates/navigation_buttons.yaml
-          vars:
-            previous_page_title: Lists
-            previous_page_id: lists
-            next_page_title: Custom Code
-            next_page_id: custom-code