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): Add schemas for connections, requests, action.

Browse Source
This commit is contained in:
SamTolmay 2021-01-26 11:05:19 +02:00
parent d781bd2d88
commit f061f9684e
3 changed files with 49 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
packages/docs/concepts/blocks.yaml
View File

@ -23,38 +23,38 @@ _ref:
type: MarkdownWithHtml
properties:
content: |
A Lowdefy page is compiled out of a arrangement of blocks. Every HTML element of this page is render as a result of a block placed and configured on the page. Blocks make it simple for Lowdefy developers to create apps since they only have to decide what block type to use, where in the layout the block should render, and what the block should do by defining the block's `properties`. How a block implements these `properties` is up to the specific block type selected.
A Lowdefy page is compiled out of a arrangement of blocks. Every HTML element of this page is render as a result of a block placed and configured on the page. Blocks make it simple for Lowdefy developers to create apps since they only have to decide what block type to use, where in the layout the block should render, and what the block should do by defining the block's `properties`. How a block implements these `properties` is up to the specific block type selected.
Lowdefy offers a list of over 30 block types to cater for a wide range of use cases. All blocks are categorized according to their primary function:
Lowdefy offers a list of over 30 block types to cater for a wide range of use cases. All blocks are categorized according to their primary function:
- `display` - Display page elements.
- `input` - Modify a value in [`state`](/state-and-context).
- `context` - Create a new [`context`](/state-and-context).
- `container` - Render other blocks into [`content areas`](/layout).
- `list` - Render [`content areas`](/layout) and blocks for each element in the data array.
When `state` updates or a requests call completes, the Lowdefy engine reevaluates all operators and rerenders blocks for which the operator evaluation is different form the previous render result. The result is _live updates_ to all blocks on a page. Operators can be used to build _live update_ logic into all block fields, except for the `id`, `type`, `areas`, `blocks` and `loading` fields.
When `state` updates or a requests call completes, the Lowdefy engine reevaluates all operators and rerenders blocks for which the operator evaluation is different form the previous render result. The result is _live updates_ to all blocks on a page. Operators can be used to build _live update_ logic into all block fields, except for the `id`, `type`, `areas`, `blocks` and `loading` fields.
# Block Schema
All Lowdefy blocks follow a __consistent__ root level schema with only 8 fields:
The schema for a Lowdefy block is:
- `id`: _String_ - __Required__ - A unique identifier for a block. For `Input` blocks the block `id` sets the field key which the block will modify in [`state`](/state-and-context). Field _dot-notation_ can be used to express fields which are nested in objects or arrays.
- `type`: _String_ - __Required__ - The is the block type identifier and defines what block to used. The block type used must either be a default block type or must defined in your app's `types` configuration.
- `properties`: _Object_ - All the settings passed to a block component.
- `properties`: _Object_ - All the settings passed to a block component. __Operators are evaluated__.
- `areas`: _Object_ - Used to set the content areas and content layout settings for `container`, `context` and `list` blocks. See [layout](/layout) for more details on how to use `areas`.
- `blocks`: _Array_ - A array of blocks to render to the default `content` area for `container`, `context` and `list` blocks. See [layout](/layout) for more details on how to use the `blocks` array.
- `events`: _Object_ - Used to set all the `events` of a block, used to define [`event`](/events-and-actions) [`actions`](/events-and-actions).
- `layout`: _Object_ - Used to define the [layout](/layout) properties for a block.
- `loading`: _Object_ - Used to overwrite a block's default loading behavior.
- `required`: _Boolean_ | _Object_ - For `input` blocks, whether or not a value value is required in [`state`](/context-and-state) when the [`Validate`](/Validate) action is called. Can be either a boolean or an object of operators evaluating if a block is required or not.
- `style`: _Css Object_ - Used to apply css style settings to the block's top level `div` element.
- `validation`: _Array_ - A list of validation tests to pass when the [`Validate`](/Validate) action is called.
- `visible`: _Boolean_ - Controls whether or not to render a block. This field can also be defined by operators which must evaluate to `false` to make the block invisible. Blocks with `visible: false` is excluded from [`state`](/state-and-context).
- `layout`: _Object_ - Used to define the [layout](/layout) properties for a block. __Operators are evaluated__.
- `loading`: _Object_ - Used to overwrite a block's default loading behavior.
- `required`: _Boolean_ | _String_ - For `input` blocks, whether or not a value value is required in [`state`](/context-and-state) when the [`Validate`](/Validate) action is called. Can be either a boolean or a string that is used as the validation error message . __Operators are evaluated__.
- `style`: _Css Object_ - Used to apply css style settings to the block's top level `div` element. __Operators are evaluated__.
- `validation`: _Array_ - A list of validation tests to pass when the [`Validate`](/Validate) action is called. __Operators are evaluated__.
- `visible`: _Boolean_ - Controls whether or not to render a block. Operators are generally used here, and must evaluate to `false` to make the block invisible. Blocks with `visible: false` are excluded from [`state`](/state-and-context). __Operators are evaluated__.
# Block types
Lowdefy has list of default block types as defined in the Lowdefy docs. The default Lowdefy blocks aim to cover a very generic implementation of the [Ant Design](https://ant.design/components/overview/) react component library. To use all the default block types, you can simply use the block `type` key, like [`Button`](/Button), [`TextInput`](/TextInput), [`Box`](/Box) and so on.
Lowdefy has list of default block types as defined in the Lowdefy docs. The default Lowdefy blocks aim to cover a very generic implementation of the [Ant Design](https://ant.design/components/overview/) react component library. To use all the default block types, you can simply use the block `type` key, like [`Button`](/Button), [`TextInput`](/TextInput), [`Box`](/Box) and so on.
###### Default block type config example:
```yaml
lowdefy: LOWDEFY_VERSION
@ -68,13 +68,13 @@ _ref:
# ... Button details
```
However, the default types can overwritten or additional types can be define as required. For example, to set a `type` for a custom implementation of [AmCharts](https://www.amcharts.com/), we can do the following. We have created a custom [Lowdefy block for AmCharts v4](https://www.npmjs.com/package/@lowdefy/blocks-amcharts) that we can use.
However, the default types can overwritten or additional types can be define as required. For example, to set a `type` for a custom implementation of [AmCharts](https://www.amcharts.com/), we can do the following. We have created a custom [Lowdefy block for AmCharts v4](https://www.npmjs.com/package/@lowdefy/blocks-amcharts) that we can use.
###### Custom block type config example:
```yaml
lowdefy: LOWDEFY_VERSION
types:
AmChartsXY:
AmChartsXY:
url: https://unpkg.com/@lowdefy/blocks-amcharts@latest/dist/meta/AmChartsXY.json
pages:
- id: example_dashboard
@ -85,8 +85,8 @@ _ref:
properties:
# ... AmCharts details
```
More details on custom blocks can be found [here](https://github.com/lowdefy/blocks-template).
More details on custom blocks can be found [here](https://github.com/lowdefy/blocks-template).
# Block loading
@ -123,7 +123,7 @@ _ref:
- `barColor`: _String_ - Color of the bars in the Lowdefy spinner logo.
- `color`: _String_ - Color of spinner logo. Default is `#f1f1f1`.
- `height`: _Number_ | _String_ - Height of the spinner block including background. Default is `100%`.
- `shaded`: _Boolean_ - Masks the spinner block including background.
- `shaded`: _Boolean_ - Masks the spinner block including background.
- `size`: _Number_ | _String_ - Size of the spinner icon. Default is `50px`.
##### IconSpinner
@ -155,7 +155,7 @@ _ref:
A input loading skeleton, used as a placeholder for input blocks with labels.
- `size`: _Enum_ - Size of the input skeleton. Options are `small`, `medium` and `large`. Default is `medium`.
- `labelHeight`: _Number_ | _String_ - Height of the label part of the input skeleton.
- `labelHeight`: _Number_ | _String_ - Height of the label part of the input skeleton.
- `inputHeight`: _Number_ | _String_ - Height of the input part of the input skeleton. Overwrites the size setting.
- `labelWidth`: _Number_ | _String_ - Width of the label part of the input skeleton. Default is `100%`.
- `width`: _Number_ | _String_ - Width of the input part of input skeleton. Default is `100%`.
@ -163,10 +163,9 @@ _ref:
##### SkeletonParagraph
A paragraph loading skeleton, used as a placeholder for text intensive section.
- `lines`: _Number_ - The number of paragraph lines to render. Default is `4`.
- `lines`: _Number_ - The number of paragraph lines to render. Default is `4`.
- `width`: _Number_ | _String_ - Width of the paragraph skeleton. Default is `100%`.
- _ref:
path: templates/navigation_buttons.yaml
vars:

21
packages/docs/concepts/connections-and-requests.yaml
View File

@ -44,7 +44,15 @@ _ref:
content: |
# Connections
Connections are defined at the root of your Lowdefy configuration, in the `connections` array. Each connection must have an `id`, a `type`, and `properties` defining the connection.
Connections are defined at the root of your Lowdefy configuration, in the `connections` array. Each connection must have an `id`, a `type`, and `properties` defining the connection. Operators in connection properties are evaluated every time a request is called.
# Connection Schema
The schema for a Lowdefy connection is:
- `id: string`: __Required__ - A unique identifier for the connection. This is used by requests to specify which connection to use.
- `type: string`: __Required__ - The connection type to be used.
- `properties: object`: The settings passed to the connection. __Operators are evaluated__.
###### Connections definition example:
```yaml
@ -66,7 +74,16 @@ _ref:
# Requests
Requests can be defined on any block, and the results of the request are available to any block in the same context. Requests must have an `id`, `type`, `connectionId` field specifying the connection to use, and `properties` defining the request settings. Requests can be called using the [`Request`](/Request) action.
Requests can be defined on any block, and the results of the request are available to any block in the same context. Requests must have an `id`, `type`, `connectionId` field specifying the connection to use, and `properties` defining the request settings. Requests can be called using the [`Request`](/Request) action. Operators in request properties are evaluated every time a request is called.
# Request Schema
The schema for a Lowdefy request is:
- `id: string`: __Required__ - A identifier for the request. It must be unique within the context the request is defined in.
- `type: string`: __Required__ - The request type to be used. It must be a type supported by the connection type.
- `connectionId: string`: __Required__ - The `id` of the connection that should be used.
- `properties: object`: The settings passed to the request. __Operators are evaluated__.
###### Requests definition example:
```yaml

9
packages/docs/concepts/events-and-actions.yaml
View File

@ -47,6 +47,15 @@ _ref:
Actions can also have a `skip` field. Operators in the `skip` field are also 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`: __Required__ - The `id` of the connection that should be used.
- `params: object`: - The input passed to the action. __Operators are evaluated__.
###### Events and actions definition example:
```yaml
- id: block_with_actions