mirror of
https://github.com/lowdefy/lowdefy.git
synced 2025-02-23 14:39:32 +08:00
83 lines
5.5 KiB
YAML
83 lines
5.5 KiB
YAML
# 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: context-and-state
|
|
pageTitle: Context and State
|
|
section: Concepts
|
|
filePath: concepts/context-and-state.yaml
|
|
content:
|
|
- id: md1
|
|
type: Markdown
|
|
properties:
|
|
content: |
|
|
#### TLDR
|
|
- The first block on a page must be a `context` category block.
|
|
- A page can have multiple `context` blocks.
|
|
- Every `context` has a single `state` object.
|
|
- All input blocks write their value to `state`, with the their `id` as the key in the `state` object.
|
|
- Input blocks which are not visible are removed from `state`.
|
|
- The `SetState` action can also modify the `state` object.
|
|
|
|
-------
|
|
|
|
A Lowdefy block with category `context` provides the environment for a part of a Lowdefy app to run in. More than one context can be placed on a page, but generally only one is needed. The first block on a page must be a `context` category block.
|
|
|
|
The standard page blocks like [`PageHeaderMenu`](/PageHeaderMenu) or [`PageSiderMenu`](/PageSiderMenu) are all `context` category blocks, and the [`Context`](/Context) block is a simple container that also provides a context.
|
|
|
|
Each context provides encapsulation to the blocks inside it. It has it's own `state` object as well as requests.
|
|
|
|
Every `input` category block inside the context will have a value in the `state` object, with the their `id` as the key in the `state` object, unless the block is not visible, in which case the input value is removed the state object.
|
|
|
|
The only other way to modify the `state` object is to use a `SetState` action. See [`SetState`](/SetState) and [`events-and-actions`](/events-and-actions) for more details.
|
|
|
|
Contexts remain even as users navigate to new pages, so if a user returns to a page, the state as they left it will remain.
|
|
|
|
# Url queries
|
|
|
|
A new context is created for each distinct URL query parameters seen by the app. This means that if a page is open with two different URL queries, two different contexts, with separate `state` objects will be created.
|
|
|
|
# Context IDs
|
|
|
|
Each context created has a identifier with the following structure:
|
|
```
|
|
{pageId}:{blockId}:{JSON stringified urlQuery object}
|
|
```
|
|
|
|
# Context data objects
|
|
|
|
A Lowdefy `context` makes some additional data object accessible via operators. These include:
|
|
|
|
- [`_global`](/_global): The `global` object is a single app level data object defined in the Lowdefy [config root](/lowdefy-schema). This object is the same for every `context`, it is also passed between the client and server. If the [`SetGlobal`](/SetGlobal) action is called, it is not consistent between clients, like different users, or a single user with multiple tabs open.
|
|
|
|
- [`_state`](/_state): A `state` object is unique to a `context` and every [`input` block](/blocks) maintains a value in it's parent `state` object. This `state` object is passed to the server when requests are called. The [`SetState`](/SetState) action can be used to modify the value of a `state` object in the same `context` from which `SetState` is called.
|
|
|
|
- [`_url_query`](/_url_query): The `urlQuery` object is used to access variables set in the url. Url query parameters can be set using the `urlQuery` field in the [`Link`](/Link) action. It can be useful to create sharable links containing some additional information other than the page route. For example setting a document id in the url so that the document can be retrieved when the link is opened during the page [`onEnter`](/events-and-actions) event. __Note that any variables set to `urlQuery` will be publicly visible__.
|
|
|
|
- [`_input`](/_input): The `input` object is unique to a page, and works similar to the `urlQuery` object. The `input` object is used to pass information between page transitions. This variable set to the `input` object are not written to the url, so they are not visible publicly but also cannot be used to share the data in a link since a `input` object is only consistent between one `context` and the next to which it links. A `input` object is set to the `input` field of the [`Link`](/Link) action when linking from one page `context` to the next.
|
|
|
|
- [`_media`](/_media): The `media` object contains some information about the client screen size etc. This is useful in order to add additional responsive logic to a page.
|
|
|
|
- [`_user`](/user-object): The `user` object contains the data in the user idToken if OpenID Connect authentication is configured and a user is logged in.
|
|
|
|
- _ref:
|
|
path: templates/navigation_buttons.yaml
|
|
vars:
|
|
previous_page_title: Lowdefy Schema
|
|
previous_page_id: lowdefy-schema
|
|
next_page_title: Blocks
|
|
next_page_id: blocks
|