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
31df2a4120
lowdefy/packages/docs/concepts/blocks.yaml
SamTolmay 969414dcaf fix(docs): Update docs for v3.5.0
2021-02-05 12:38:26 +02:00

238 lines
15 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: blocks
pageTitle: Blocks
section: Concepts
content:
- id: md1
type: MarkdownWithCode
properties:
content: |
#### TLDR
- All user interfaces in Lowdefy are assembled out of blocks.
##### Block types
- There a five block categories: `display`, `input`, `context`, `container` and `list`.
- Operators re-evaluate on every [`state`](/context-and-state) update or as request calls complete. This allows blocks to _live update_.
- Lowdefy has built in default block types, however this can be overwritten or extended with custom blocks by defining `types` on the Lowdefy config root.
- `input` blocks maintain a value in [`state`](/context-and-state) matching the block `id` key. _Dot notation_ applies to specify nested fields.
##### Block validation
- Field level input validation can be achieved marking a `input` block as `required` or by specifying a list of `validation` tests.
- Validation is invoked using the [`Validate`](/Validate) action, and applies to all `input` fields in the [`context`](/context-and-state).
##### Block loading
- By default all blocks render a loading skeleton when the block's source code is fetched or while the block is waiting on data from a request.
- A block's default loading can be overwritten by defining custom `loading` settings on a block.
-------
A Lowdefy page is compiled out of an 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:
- `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 from 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
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. __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. __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.
###### Default block type config example:
```yaml
lowdefy: LOWDEFY_VERSION
pages:
- id: example_dashboard
type: PageHeaderMenu
blocks:
- id: basic_chart
type: Button
properties:
# ... 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.
###### Custom block type config example:
```yaml
lowdefy: LOWDEFY_VERSION
types:
AmChartsXY:
url: https://unpkg.com/@lowdefy/blocks-amcharts@latest/dist/meta/AmChartsXY.json
pages:
- id: example_dashboard
type: Context
blocks:
- id: basic_chart
type: AmChartsXY
properties:
# ... AmCharts details
```
More details on custom blocks can be found [here](https://github.com/lowdefy/blocks-template).
# Input block validation
All `input` block types maintain a value in [`state`](/context-and-state). This value is set to the field name matching the block `id`. Nested fields can be created by using _dot notation_ in the `id` to specify the field path.
Client side field validation can be applied setting the `required` and / or `validation` block fields. The following schema applies to `required` and `validation`.
Field validation is first evaluated when the [`Validate`](/Validate) action is invoked on a page [`context`](/context-and-state).
##### `required` schema:
`requried` can be a `boolean` or `string` type. When `required: true` the field label will indicate this with a red dot for user feedback, and a value will have to be supplied in to the field in order to pass validation. If `required` is set to a `string`, this string will be used as the feedback message when the validation fails.
```yaml
- id: name
type: TextInput
required: Please provide your name.
properties:
title: Name
```
##### `validation` schema:
The `validation` field takes a `array` of test `objects` to evaluate before passing the field validation. This list of tests are evaluated sequentially, so the test that fails first will be used as the feedback message to the user.
The schema for the validation test `objects`:
- `pass: boolean`: __Required__ - The test that validates if this item passes or not. This is usually written as operators which evaluates to a `true` or `false`. __Operators are evaluated__.
- `message: string`: __Required__ - The feedback message to the user if this validation tests fails. __Operators are evaluated__.
- `status: enum`: The feedback type to present to the user. Option are `error` and `warning`. Default is `error`. __Operators are evaluated__.
The following `validation` example first verifies that something was entered into the `email` field, then checks that the field passes a email regex validation using the [`_regex`](/_regex) operator:
```yaml
- id: email
type: TextInput
validation:
- message: Please enter a email address.
status: error
pass:
_not:
_not:
_state: email
- message: Please provide a valid email address.
status: error
pass:
_regex: '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$'
properties:
title: Email
```
# Block loading
Block loading renders a placeholder block while the block component is being fetched, or a block is waiting on a request to return before to rendering the block. This allows for a smoother user experience and reduces 'bounce' in the user interface as more blocks takes up their full width and height on the page while in a loading state.
By default, Lowdefy tries to give a reasonable definition for how much space a block should take up in while loading, however this can vary depending on how the block is used. The `loading` property on blocks allows the Lowdefy developer to set a custom loading configuration for a block.
##### Custom block `loading` example:
```yaml
pages:
- id: page_one
type: Context
blocks:
# ...
- id: paragraph_one
type: Title
loading:
type: SkeletonParagraph
properties:
lines: 1
properties:
content: Lorem ipsum dolor sit amet.
# ...
```
## Loading placeholder types
The following loading placeholder types are available:
##### Spinner
A Lowdefy logo loading spinner placed at the center of the block. Often used as the full page loading spinner logo. The following `properties` apply to `Spinner`:
- `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.
- `size: number | string`: Size of the spinner icon. Default is `50px`.
##### IconSpinner
A spinning loading icon. The following `properties` apply to `IconSpinner`:
- `size: number | enum`: Size of the spinner icon. Options are `small`, `medium` and `large`. Default is `20px`.
##### Skeleton
A rectangular loading skeleton to fill the full size of the block. The following `properties` apply to `Skeleton`:
- `height: number | string`: Height of the skeleton block. Default is `100%`.
- `width: number | string`: Width of the skeleton block. Default is `100%`.
##### SkeletonAvatar
A avatar loading skeleton. The following `properties` apply to `SkeletonAvatar`:
- `size: number | enum`: Size of the avatar skeleton. Options are `small`, `medium` and `large`. Default is `32px`.
- `shape: enum`: Shape of the avatar skeleton. Options are `square` and `round`. Default is `round`.
##### SkeletonButton
A button loading skeleton, matches the size of [`Button`](/Button) blocks. The following `properties` apply to `SkeletonButton`:
- `size: enum`: Size of the button skeleton. Options are `small`, `medium` and `large`. Default is `medium`.
- `shape: enum`: Shape of the button skeleton corners. Options are `square` and `round`. Default is `round`.
- `height: number | string`: Height of the button skeleton. Overwrites the size setting.
- `width: number | string`: Width of the button skeleton. Default is `100%`.
##### SkeletonInput
A input loading skeleton, used as a placeholder for input blocks with labels. The following `properties` apply to `SkeletonInput`:
- `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.
- `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%`.
##### SkeletonParagraph
A paragraph loading skeleton, used as a placeholder for text intensive section. The following `properties` apply to `SkeletonParagraph`:
- `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:
previous_page_title: Context and State
previous_page_id: context-and-state
next_page_title: Layout
next_page_id: layout
Reference in New Issue View Git Blame Copy Permalink