@lowdefy/docs-content 6.1.0 → 7.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/content/actions/downloadcsv.md +1 -1
- package/content/actions/emailotpsend.md +58 -0
- package/content/actions/emailotpverify.md +79 -0
- package/content/actions/getlocalstorage.md +43 -0
- package/content/actions/link.md +47 -1
- package/content/actions/login.md +25 -5
- package/content/actions/logout.md +7 -5
- package/content/actions/magiclinkverify.md +117 -0
- package/content/actions/pdfmake.md +2 -2
- package/content/actions/posthogalias.md +29 -0
- package/content/actions/posthogcapture.md +49 -0
- package/content/actions/posthogcapturepageleave.md +38 -0
- package/content/actions/posthogfeatureflag.md +50 -0
- package/content/actions/posthoggroup.md +37 -0
- package/content/actions/posthogidentify.md +54 -0
- package/content/actions/posthoginit.md +96 -0
- package/content/actions/posthogoptin.md +29 -0
- package/content/actions/posthogoptout.md +29 -0
- package/content/actions/posthogpageview.md +37 -0
- package/content/actions/posthogreloadfeatureflags.md +47 -0
- package/content/actions/posthogreset.md +28 -0
- package/content/actions/posthogsetpersonproperties.md +36 -0
- package/content/actions/removelocalstorage.md +28 -0
- package/content/actions/resetvalidation.md +7 -3
- package/content/actions/setdarkmode.md +3 -3
- package/content/actions/setglobal.md +2 -0
- package/content/actions/setlocale.md +1 -1
- package/content/actions/setlocalstorage.md +34 -0
- package/content/actions/validate.md +7 -4
- package/content/adapter-reference/mongodbauthadapter.md +46 -0
- package/content/agents/agent-endpoint-tools.md +24 -0
- package/content/agents/agent-properties.md +13 -3
- package/content/agents/agent-server-hooks.md +1 -1
- package/content/agents/agentchat.md +43 -7
- package/content/agents/agentconversations.md +42 -8
- package/content/agents/agents-introduction.md +107 -0
- package/content/callback-reference/auth0logoutcallback.md +54 -0
- package/content/concepts/ai-agent-docs.md +455 -106
- package/content/concepts/blocks.md +150 -0
- package/content/concepts/connections-and-requests.md +402 -0
- package/content/concepts/custom-html.md +42 -0
- package/content/concepts/custom-styling.md +50 -5
- package/content/concepts/dynamic-page-content.md +309 -0
- package/content/concepts/events-and-actions.md +154 -2
- package/content/concepts/four-primitives.md +31 -0
- package/content/concepts/html-attributes.md +293 -0
- package/content/concepts/i18n.md +8 -3
- package/content/concepts/keyboard-shortcuts.md +2 -2
- package/content/concepts/layout-overview.md +1 -1
- package/content/concepts/logger.md +99 -0
- package/content/concepts/lowdefy-api.md +1319 -0
- package/content/concepts/lowdefy-schema.md +136 -3
- package/content/concepts/menus.md +8 -7
- package/content/concepts/module-authoring.md +76 -5
- package/content/concepts/modules.md +3 -1
- package/content/concepts/notifications.md +180 -0
- package/content/concepts/operators.md +7 -0
- package/content/concepts/page-and-app-state.md +252 -0
- package/content/concepts/page-paths.md +209 -0
- package/content/concepts/theming.md +582 -0
- package/content/connections/aigateway.md +375 -0
- package/content/connections/anthropic.md +169 -2
- package/content/connections/awss3.md +178 -2
- package/content/connections/axioshttp.md +181 -0
- package/content/connections/google.md +169 -2
- package/content/connections/mongodb.md +1014 -3
- package/content/connections/openai-connection.md +169 -2
- package/content/connections/sendgridmail.md +2 -0
- package/content/connections/smtp.md +3 -1
- package/content/connections/treg.md +329 -0
- package/content/container-blocks/affix.md +47 -7
- package/content/container-blocks/alert.md +76 -24
- package/content/container-blocks/badge.md +100 -24
- package/content/container-blocks/box.md +9 -9
- package/content/container-blocks/card.md +132 -27
- package/content/container-blocks/carousel.md +60 -7
- package/content/container-blocks/collapse.md +153 -9
- package/content/container-blocks/configprovider.md +35 -13
- package/content/container-blocks/confirmmodal.md +69 -23
- package/content/container-blocks/content.md +62 -98
- package/content/container-blocks/descriptions.md +45 -4
- package/content/container-blocks/drawer.md +139 -28
- package/content/container-blocks/dropdownmenu.md +119 -31
- package/content/container-blocks/flex.md +40 -62
- package/content/container-blocks/footer.md +15 -11
- package/content/container-blocks/googlemapsheatmap.md +1 -1
- package/content/container-blocks/googlemapsscript.md +2 -2
- package/content/container-blocks/header.md +71 -36
- package/content/container-blocks/label.md +34 -7
- package/content/container-blocks/layout.md +52 -34
- package/content/container-blocks/masonry.md +17 -71
- package/content/container-blocks/mobilemenu.md +131 -88
- package/content/container-blocks/modal.md +161 -26
- package/content/container-blocks/pageheadermenu.md +138 -31
- package/content/container-blocks/pagesidebarlayout.md +230 -27
- package/content/container-blocks/pagesidermenu.md +153 -43
- package/content/container-blocks/popover.md +34 -31
- package/content/container-blocks/result.md +32 -21
- package/content/container-blocks/sider.md +85 -122
- package/content/container-blocks/span.md +7 -7
- package/content/container-blocks/spinner.md +3 -3
- package/content/container-blocks/splitter.md +150 -68
- package/content/container-blocks/tabs.md +64 -12
- package/content/container-blocks/tooltip.md +22 -46
- package/content/container-blocks/watermark.md +22 -4
- package/content/controls/parallel_for.md +21 -2
- package/content/controls/reject.md +24 -3
- package/content/controls/return.md +17 -1
- package/content/controls/throw.md +1 -0
- package/content/controls/try.md +4 -2
- package/content/controls/while.md +46 -0
- package/content/deployment/deployment-environments.md +10 -7
- package/content/deployment/docker.md +22 -7
- package/content/deployment/node-server.md +4 -0
- package/content/deployment/vercel.md +17 -6
- package/content/display-blocks/aggrid.md +36 -19
- package/content/display-blocks/anchor.md +16 -15
- package/content/display-blocks/avatar.md +57 -37
- package/content/display-blocks/breadcrumb.md +70 -21
- package/content/display-blocks/button.md +93 -19
- package/content/display-blocks/calendar.md +12 -0
- package/content/display-blocks/clickablehtml.md +239 -0
- package/content/display-blocks/dangeroushtml.md +1 -1
- package/content/display-blocks/difflist.md +1 -1
- package/content/display-blocks/difftimeline.md +1 -1
- package/content/display-blocks/divider.md +64 -3
- package/content/display-blocks/dropdownbutton.md +81 -30
- package/content/display-blocks/echart.md +35 -1
- package/content/display-blocks/eventlog.md +363 -0
- package/content/display-blocks/floatbutton.md +129 -42
- package/content/display-blocks/html.md +61 -1
- package/content/display-blocks/icon.md +250 -67
- package/content/display-blocks/img.md +2 -2
- package/content/display-blocks/menu.md +146 -73
- package/content/display-blocks/message.md +38 -124
- package/content/display-blocks/notification.md +94 -222
- package/content/display-blocks/paragraph.md +59 -9
- package/content/display-blocks/pollingtimer.md +263 -0
- package/content/display-blocks/progress.md +96 -17
- package/content/display-blocks/qrcode.md +19 -4
- package/content/display-blocks/s3download.md +1 -1
- package/content/display-blocks/search.md +19 -9
- package/content/display-blocks/skeletonbutton.md +1 -0
- package/content/display-blocks/skeletoninput.md +1 -0
- package/content/display-blocks/statistic.md +75 -17
- package/content/display-blocks/steps.md +58 -25
- package/content/display-blocks/table.md +2527 -0
- package/content/display-blocks/tablelight.md +621 -0
- package/content/display-blocks/tag.md +102 -17
- package/content/display-blocks/title.md +50 -11
- package/content/display-blocks/tour.md +33 -23
- package/content/input-blocks/autocomplete.md +81 -9
- package/content/input-blocks/buttonselector.md +45 -8
- package/content/input-blocks/captcha.md +40 -0
- package/content/input-blocks/checkboxselector.md +97 -7
- package/content/input-blocks/checkboxswitch.md +33 -3
- package/content/input-blocks/colorselector.md +63 -14
- package/content/input-blocks/daterangeselector.md +165 -45
- package/content/input-blocks/dateselector.md +139 -41
- package/content/input-blocks/datetimeselector.md +158 -49
- package/content/input-blocks/inputgallery.md +3 -3
- package/content/input-blocks/intentinput.md +207 -0
- package/content/input-blocks/monthselector.md +120 -52
- package/content/input-blocks/multipleselector.md +150 -39
- package/content/input-blocks/numberinput.md +98 -12
- package/content/input-blocks/pagination.md +70 -14
- package/content/input-blocks/paragraphinput.md +51 -37
- package/content/input-blocks/passwordinput.md +60 -6
- package/content/input-blocks/phonenumberinput.md +59 -26
- package/content/input-blocks/placesautocomplete.md +319 -0
- package/content/input-blocks/radioselector.md +83 -7
- package/content/input-blocks/ratingslider.md +57 -26
- package/content/input-blocks/s3uploadbutton.md +24 -24
- package/content/input-blocks/s3uploaddragger.md +3 -3
- package/content/input-blocks/s3uploadphoto.md +5 -5
- package/content/input-blocks/segmentedselector.md +72 -32
- package/content/input-blocks/selector.md +109 -21
- package/content/input-blocks/switch.md +65 -17
- package/content/input-blocks/tableinput.md +445 -0
- package/content/input-blocks/tagmultipleselector.md +114 -0
- package/content/input-blocks/tagselector.md +114 -0
- package/content/input-blocks/textarea.md +32 -3
- package/content/input-blocks/textinput.md +70 -29
- package/content/input-blocks/tiptapinput.md +1 -1
- package/content/input-blocks/tiptapmentioninput.md +2 -2
- package/content/input-blocks/titleinput.md +39 -12
- package/content/input-blocks/treeinput.md +49 -25
- package/content/input-blocks/treemultipleselector.md +127 -10
- package/content/input-blocks/treeselector.md +97 -9
- package/content/input-blocks/upload.md +64 -15
- package/content/input-blocks/uploaddragger.md +17 -1
- package/content/input-blocks/uploadphoto.md +18 -1
- package/content/input-blocks/weekselector.md +120 -55
- package/content/learn/introduction.md +27 -0
- package/content/learn/quickstart.md +53 -0
- package/content/list-blocks/controlledlist.md +24 -15
- package/content/list-blocks/list.md +11 -11
- package/content/list-blocks/masonrylist.md +7 -34
- package/content/migration/auth-upgrade.md +337 -0
- package/content/migration/upgrade-guide.md +1 -0
- package/content/migration/v3-to-v4.md +417 -0
- package/content/migration/v6-to-v7.md +620 -0
- package/content/operators/_agent.md +155 -0
- package/content/operators/_app.md +2 -1
- package/content/operators/_array.md +122 -1
- package/content/operators/_build.md +1 -0
- package/content/operators/_credential.md +57 -0
- package/content/operators/_cron.md +292 -0
- package/content/operators/_date.md +2 -0
- package/content/operators/_error.md +24 -1
- package/content/operators/_get.md +6 -6
- package/content/operators/_hmac.md +78 -0
- package/content/operators/_js.md +2 -1
- package/content/operators/_location.md +1 -1
- package/content/operators/_media.md +13 -0
- package/content/operators/_module.md +56 -2
- package/content/operators/_operator.md +17 -3
- package/content/operators/_path_params.md +82 -0
- package/content/operators/_ref.md +258 -0
- package/content/operators/_request.md +1 -1
- package/content/operators/_request_details.md +6 -0
- package/content/operators/_type.md +14 -3
- package/content/operators/_url_query.md +2 -0
- package/content/operators/_user.md +3 -3
- package/content/plugins/plugins-actions.md +10 -0
- package/content/plugins/plugins-connections.md +25 -0
- package/content/plugins/plugins-dev.md +66 -0
- package/content/plugins/plugins-icon-sets.md +267 -0
- package/content/plugins/plugins-introduction.md +27 -1
- package/content/plugins/plugins.md +19 -0
- package/content/plugins/posthog.md +359 -0
- package/content/provider-reference/auth-js-providers.md +107 -0
- package/content/provider-reference/openidconnectprovider.md +44 -0
- package/content/recipes/recipes.md +16 -0
- package/content/reference/actions-reference.md +31 -0
- package/content/reference/blocks-reference.md +35 -0
- package/content/reference/cli.md +403 -0
- package/content/reference/connections-reference.md +23 -0
- package/content/reference/operators-reference.md +47 -0
- package/content/reference/reference.md +16 -0
- package/content/reference/schema-reference.md +12 -0
- package/content/testing/config-tests.md +677 -0
- package/content/testing/e2e-configuration.md +31 -1
- package/content/testing/e2e-getting-started.md +1 -1
- package/content/testing/e2e-introduction.md +1 -1
- package/content/testing/e2e-writing-tests.md +12 -1
- package/content/testing/explore-pull-request.md +136 -0
- package/content/testing/journey-data-sets.md +326 -0
- package/content/tutorial/tutorial-actions-operators.md +2 -2
- package/content/tutorial/tutorial-add-blocks.md +2 -2
- package/content/tutorial/tutorial-create-page.md +48 -2
- package/content/tutorial/tutorial-display-data-page.md +3 -3
- package/content/tutorial/tutorial-requests-api.md +155 -0
- package/content/tutorial/tutorial-requests-sql.md +153 -0
- package/content/tutorial/tutorial-start.md +66 -1
- package/content/user-authentication/auth-configuration.md +267 -0
- package/content/user-authentication/auth-providers.md +24 -0
- package/content/user-authentication/auth-steps.md +141 -0
- package/content/user-authentication/login-and-logout.md +160 -8
- package/content/user-authentication/mcp-oauth.md +424 -0
- package/content/user-authentication/organizations.md +246 -0
- package/content/user-authentication/protected-pages-apis.md +97 -0
- package/content/user-authentication/roles.md +49 -0
- package/content/user-authentication/two-factor.md +229 -0
- package/content/user-authentication/user-object.md +58 -0
- package/content/user-authentication/users-introduction.md +8 -0
- package/content/websockets/websocket-publish.md +105 -0
- package/content/websockets/websocket-subscriptions.md +136 -0
- package/content/websockets/websockets-introduction.md +101 -0
- package/hazards.json +44 -0
- package/index.json +3691 -14
- package/package.json +11 -1
- package/scripts/collectImportedFiles.js +80 -0
- package/scripts/extractAgentDocs.js +41 -30
- package/scripts/hashDocSources.js +38 -0
- package/scripts/isRedirectPage.js +26 -0
- package/scripts/recordSourceHashes.js +100 -0
- package/scripts/resolvePageSections.js +42 -0
- package/scripts/sectionKind.js +27 -0
- package/content/concepts/cli.md +0 -223
- package/content/other/introduction.md +0 -39
- package/content/other/next-auth-providers.md +0 -3
- /package/content/{other → actions}/updatesession.md +0 -0
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
Lowdefy provides several ways to style blocks and customize the look of your app:
|
|
4
4
|
|
|
5
5
|
- **`class`** — Apply CSS class names (including Tailwind CSS utility classes) to blocks.
|
|
6
|
-
- **`style`** — Apply inline CSS styles to blocks. Use
|
|
6
|
+
- **`style`** — Apply inline CSS styles to blocks. Use `.`-prefixed keys to target specific parts (CSS slots).
|
|
7
7
|
- **`properties.theme`** — Override antd design tokens per block. See [Theming](/theming) for details.
|
|
8
8
|
- **`public/styles.css`** — A global CSS file for custom styles.
|
|
9
9
|
|
|
@@ -11,7 +11,7 @@ Lowdefy provides several ways to style blocks and customize the look of your app
|
|
|
11
11
|
|
|
12
12
|
The `class` property applies CSS class names to a block. [Tailwind CSS](https://tailwindcss.com/) is always available in Lowdefy apps, so you can use any Tailwind utility classes directly.
|
|
13
13
|
|
|
14
|
-
`class` can be a string, an array of strings,
|
|
14
|
+
`class` can be a string, an array of strings, an object keyed by the block's CSS keys, or an operator that computes the classes at runtime:
|
|
15
15
|
|
|
16
16
|
```yaml
|
|
17
17
|
# String — applied to the block wrapper
|
|
@@ -27,15 +27,60 @@ The `class` property applies CSS class names to a block. [Tailwind CSS](https://
|
|
|
27
27
|
- shadow-lg
|
|
28
28
|
- rounded-xl
|
|
29
29
|
|
|
30
|
-
# Object — target specific parts of the block using CSS keys (
|
|
30
|
+
# Object — target specific parts of the block using CSS keys (. prefix)
|
|
31
31
|
- id: my_card
|
|
32
32
|
type: Card
|
|
33
33
|
class:
|
|
34
34
|
.element: "shadow-lg"
|
|
35
35
|
.header: "bg-gray-100"
|
|
36
36
|
.body: "p-8"
|
|
37
|
+
|
|
38
|
+
# Operator — the block's classes are computed at runtime
|
|
39
|
+
- id: status_badge
|
|
40
|
+
type: Box
|
|
41
|
+
class:
|
|
42
|
+
_if:
|
|
43
|
+
test:
|
|
44
|
+
_eq:
|
|
45
|
+
- _state: status
|
|
46
|
+
- error
|
|
47
|
+
then: bg-red-100 text-red-700
|
|
48
|
+
else: bg-green-100 text-green-700
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
An operator's result may be a string, an array of strings, or an object of `{ class: boolean }` where each class with a truthy value is applied:
|
|
52
|
+
|
|
53
|
+
```yaml
|
|
54
|
+
- id: status_badge
|
|
55
|
+
type: Box
|
|
56
|
+
class:
|
|
57
|
+
_if:
|
|
58
|
+
test:
|
|
59
|
+
_eq:
|
|
60
|
+
- _state: status
|
|
61
|
+
- error
|
|
62
|
+
then:
|
|
63
|
+
bg-red-100: true
|
|
64
|
+
text-red-700: true
|
|
65
|
+
else: bg-green-100
|
|
37
66
|
```
|
|
38
67
|
|
|
68
|
+
An operator at the root of `class` computes the classes of the block wrapper. To compute a specific part's classes, place the operator under that CSS key:
|
|
69
|
+
|
|
70
|
+
```yaml
|
|
71
|
+
- id: my_card
|
|
72
|
+
type: Card
|
|
73
|
+
class:
|
|
74
|
+
.header:
|
|
75
|
+
_if:
|
|
76
|
+
test:
|
|
77
|
+
_state: highlighted
|
|
78
|
+
then: bg-yellow-100
|
|
79
|
+
else: bg-gray-100
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
> **Note:** An operator's result is never expanded into a map of CSS keys — a root operator always sets the block wrapper's classes. A result with dot-prefixed keys (`{ .element: p-4 }`) is reported as a config error, and those keys are not applied as classes.
|
|
83
|
+
|
|
39
84
|
Tailwind responsive prefixes work as expected:
|
|
40
85
|
|
|
41
86
|
```yaml
|
|
@@ -58,7 +103,7 @@ See [Theming](/theming) for the full list of bridged tokens and how to add custo
|
|
|
58
103
|
|
|
59
104
|
## The `style` property
|
|
60
105
|
|
|
61
|
-
The `style` property applies inline CSS styles to a block. When used with flat CSS properties (no
|
|
106
|
+
The `style` property applies inline CSS styles to a block. When used with flat CSS properties (no `.` prefix), it targets the block's layout wrapper:
|
|
62
107
|
|
|
63
108
|
```yaml
|
|
64
109
|
- id: my_block
|
|
@@ -103,7 +148,7 @@ Each block's documentation page lists its supported CSS keys.
|
|
|
103
148
|
|
|
104
149
|
Each block declares named style targets in its `meta.cssKeys`. For example, the [Card](/Card) block supports: `element`, `header`, `body`, `cover`, `actions`, `extra`.
|
|
105
150
|
|
|
106
|
-
Both `class` (object form) and `style` use
|
|
151
|
+
Both `class` (object form) and `style` use `.`-prefixed versions of these keys to target specific parts of a block. The `.` prefix mirrors CSS selector convention and avoids confusion with CSS property names.
|
|
107
152
|
|
|
108
153
|
To find the CSS keys for a block, check the block's documentation page.
|
|
109
154
|
|
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
# Dynamic Page Content
|
|
2
|
+
|
|
3
|
+
Dynamic page content lets parts of a page — or a whole page — be resolved on the server at page load. You place a `Dynamic` block on a page and point it at an [API endpoint](/lowdefy-api). When the page is requested, the server calls the endpoint's routine in-process, the routine returns block config, and the server validates that config and splices it into the page before responding. The client renders the result like any other page.
|
|
4
|
+
|
|
5
|
+
Dynamic page content is useful when the structure of a page depends on runtime data:
|
|
6
|
+
|
|
7
|
+
- A dashboard whose sections depend on the user's role, plan, or feature flags.
|
|
8
|
+
- A form generated from a workflow definition stored in a database.
|
|
9
|
+
- A product page whose layout comes from a CMS record.
|
|
10
|
+
- Table views, kanban columns, or navigation derived from tenant configuration.
|
|
11
|
+
|
|
12
|
+
For content where only the _data_ changes, use [requests](/connections-and-requests) — they are cached, re-fetchable, and don't reset page state. Reach for dynamic page content when the _blocks themselves_ need to change per request.
|
|
13
|
+
|
|
14
|
+
## How It Works
|
|
15
|
+
|
|
16
|
+
1. A user requests a page containing a `Dynamic` block.
|
|
17
|
+
2. The server checks page authorization as usual, then calls the endpoint configured on each `Dynamic` block — in-process, no HTTP. The endpoint's own auth is also checked against the user's session.
|
|
18
|
+
3. The routine executes with a payload containing the block's `params`, the `pageId`, the `blockId`, and the page request's `urlQuery` and `pathParams`.
|
|
19
|
+
4. The routine returns `{ blocks: [...] }` — ordinary Lowdefy block config.
|
|
20
|
+
5. The server builds and validates the returned blocks: block, action and operator types must be in the app's client bundle, block properties are validated against each block type's schema, and `Request` actions must reference requests defined statically on the page.
|
|
21
|
+
6. The validated blocks become the `Dynamic` block's content, and the page is sent to the client.
|
|
22
|
+
|
|
23
|
+
If resolution fails, the `Dynamic` block renders its `fallback` slot (or nothing) and the error is logged on the server — the page still loads. Set `required: true` to fail the whole page request instead.
|
|
24
|
+
|
|
25
|
+
## The Dynamic Block
|
|
26
|
+
|
|
27
|
+
```yaml
|
|
28
|
+
- id: insights
|
|
29
|
+
type: Dynamic
|
|
30
|
+
properties:
|
|
31
|
+
endpointId: resolve_insights # Required. The endpoint that resolves this content.
|
|
32
|
+
params: # Optional. Static values passed to the endpoint.
|
|
33
|
+
area: insights
|
|
34
|
+
required: false # Optional. true fails the page load on resolution failure.
|
|
35
|
+
types: # Optional. Extra types the endpoint may return.
|
|
36
|
+
blocks:
|
|
37
|
+
- Statistic
|
|
38
|
+
slots:
|
|
39
|
+
fallback: # Optional. Rendered when resolution fails.
|
|
40
|
+
blocks:
|
|
41
|
+
- id: insights_unavailable
|
|
42
|
+
type: Html
|
|
43
|
+
properties:
|
|
44
|
+
html: Insights are unavailable right now.
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`params` must not contain operators — the page config is static. Runtime values belong in the endpoint routine, which reads the payload with `_payload` and the session with `_user`.
|
|
48
|
+
|
|
49
|
+
A page that should be entirely dynamic is just a page whose body is a single `Dynamic` block.
|
|
50
|
+
|
|
51
|
+
## The Resolver Endpoint
|
|
52
|
+
|
|
53
|
+
The endpoint is a normal API endpoint. Use `type: InternalApi` so it has no HTTP route — it is then only callable by the server itself.
|
|
54
|
+
|
|
55
|
+
The endpoint receives this payload:
|
|
56
|
+
|
|
57
|
+
- `params: object` - The `Dynamic` block's `params`, verbatim.
|
|
58
|
+
- `pageId: string` - The page being resolved.
|
|
59
|
+
- `blockId: string` - The `Dynamic` block's id.
|
|
60
|
+
- `urlQuery: object` - The query parameters of the page request.
|
|
61
|
+
- `pathParams: object` - The values of the placeholders in the page's [`path`](/page-paths), as strings. `{}` for a page without placeholders.
|
|
62
|
+
|
|
63
|
+
The routine must return an object with a `blocks` array:
|
|
64
|
+
|
|
65
|
+
```yaml
|
|
66
|
+
api:
|
|
67
|
+
- id: resolve_insights
|
|
68
|
+
type: InternalApi
|
|
69
|
+
auth:
|
|
70
|
+
public: false
|
|
71
|
+
routine:
|
|
72
|
+
- id: get_sections
|
|
73
|
+
type: MongoDBFind
|
|
74
|
+
connectionId: mongodb
|
|
75
|
+
properties:
|
|
76
|
+
query:
|
|
77
|
+
roles:
|
|
78
|
+
$in:
|
|
79
|
+
_user: roles
|
|
80
|
+
area:
|
|
81
|
+
_payload: params.area
|
|
82
|
+
- :return:
|
|
83
|
+
blocks:
|
|
84
|
+
_array.map:
|
|
85
|
+
on:
|
|
86
|
+
_step: get_sections
|
|
87
|
+
callback:
|
|
88
|
+
_function:
|
|
89
|
+
__object.assign:
|
|
90
|
+
- id:
|
|
91
|
+
__args: 0.section_id
|
|
92
|
+
type: Statistic
|
|
93
|
+
properties:
|
|
94
|
+
title:
|
|
95
|
+
__args: 0.title
|
|
96
|
+
value:
|
|
97
|
+
__args: 0.value
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
All operators registered on the server — including shared operators like `_state`, `_if` and `_string` — are evaluated during `:return` (`_state` reads the routine's own `:set_state` state). To defer an operator to the client instead, prefix it with one extra underscore, the same convention `_function` bodies use for `__args`:
|
|
101
|
+
|
|
102
|
+
```yaml
|
|
103
|
+
- :return:
|
|
104
|
+
blocks:
|
|
105
|
+
- id: greeting
|
|
106
|
+
type: Html
|
|
107
|
+
properties:
|
|
108
|
+
html:
|
|
109
|
+
__state: name_input # unescaped to `_state` — evaluates on the client
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The server strips one leading underscore from `__`-prefixed keys in the returned config, so `__state` reaches the client as `_state` and binds to page state like any static block. Client-only operators (`_request`, `_global`, ...) have no server implementation and need no escaping, but the `__` form works for them too and is the consistent style.
|
|
113
|
+
|
|
114
|
+
> **Never place `_secret` in returned block config.** It evaluates during `:return` and the resulting value ships to the browser.
|
|
115
|
+
|
|
116
|
+
### Data in the returned config is literal
|
|
117
|
+
|
|
118
|
+
While a Dynamic block's endpoint evaluates its `:return`, data read at runtime stays data. That covers step results, the payload, routine state, `:for` items, and values built from data, such as `_json.parse` of a stored string. Three rules apply:
|
|
119
|
+
|
|
120
|
+
- **Data cannot carry operators.** No operator may return a value that contains operators. A record holding `{ _request: ... }` or `{ __state: ... }` fails resolution, and the block renders its fallback. The error names the operator and where in its result the operator was found.
|
|
121
|
+
- **Data cannot be a block or an action.** Without a [dynamic blocks policy](#dynamic-blocks-policies), every block and action in the returned content must be written in the `:return` config. Data may fill values inside those blocks (an id, a title, a type, a list of options), but a block or action that is itself data an operator returned, or a copy of it, fails resolution. To render stored block config, check it with a `ValidateDynamic` step under a policy.
|
|
122
|
+
- **Data cannot become an operator by merging.** An object from data that `_object.assign` merges with other config must not be left with an operator key alone, for example next to a key whose value is a function or evaluates to undefined on the client.
|
|
123
|
+
|
|
124
|
+
Data may nest at most 200 levels deep; deeper data fails resolution with an error saying so. Only keys that name one of the app's operators count as operators. Data such as a search hit's `{ _score: 0.5 }` or `{ _source: { ... } }` stays data.
|
|
125
|
+
|
|
126
|
+
Write client operators in the `:return` config itself. Only operators that pass their own already-checked params through — `_if`, `_switch`, `_if_none`, `_get`, `_args`, `_function`, `_log`, `_array` and `_object` (except `_object.fromEntries` and `_object.defineProperty`) — may return them, so mapping data rows into blocks with `_array.map` and `_function` works as shown above.
|
|
127
|
+
|
|
128
|
+
These patterns return config through data and fail resolution:
|
|
129
|
+
|
|
130
|
+
- **Blocks built up in routine state** (`:set_state` in a loop, then `_state` in `:return`). Build the list inside `:return` with `_array.map` or `_array.concat`.
|
|
131
|
+
- **Blocks returned by a nested endpoint** and read with `_step`. Share block config with `_ref` instead.
|
|
132
|
+
- **A `:for` over a literal list of block configs**, read with `_item`. Map the list inside `:return`.
|
|
133
|
+
- **Blocks built by `_js` or `_jsonata`.** Return the data from them and map it into blocks inside `:return`.
|
|
134
|
+
- **Stored block config returned as it is**, whether read directly, picked out with `_get`, or copied or extended by an `_array.map` callback (`__args: 0`, `__object.assign`). Put the Dynamic block under a policy and return the content through `ValidateDynamic` (see [Rendering stored content under a policy](#rendering-stored-content-under-a-policy)).
|
|
135
|
+
|
|
136
|
+
## Using urlQuery in the Routine
|
|
137
|
+
|
|
138
|
+
The page request's query string is forwarded to the resolver as `urlQuery` in the payload. A page loaded as `/products?category=shoes&sort=price` resolves with `urlQuery: { category: 'shoes', sort: 'price' }`:
|
|
139
|
+
|
|
140
|
+
```yaml
|
|
141
|
+
api:
|
|
142
|
+
- id: resolve_products
|
|
143
|
+
type: InternalApi
|
|
144
|
+
routine:
|
|
145
|
+
- id: get_products
|
|
146
|
+
type: MongoDBFind
|
|
147
|
+
connectionId: mongodb
|
|
148
|
+
properties:
|
|
149
|
+
query:
|
|
150
|
+
category:
|
|
151
|
+
_payload: urlQuery.category
|
|
152
|
+
options:
|
|
153
|
+
sort:
|
|
154
|
+
- - _payload: urlQuery.sort
|
|
155
|
+
- 1
|
|
156
|
+
- :return:
|
|
157
|
+
blocks:
|
|
158
|
+
- id: product_count
|
|
159
|
+
type: Html
|
|
160
|
+
properties:
|
|
161
|
+
html:
|
|
162
|
+
_string.concat:
|
|
163
|
+
- 'Found '
|
|
164
|
+
- _array.length:
|
|
165
|
+
_step: get_products
|
|
166
|
+
- ' products in "'
|
|
167
|
+
- _payload: urlQuery.category
|
|
168
|
+
- '"'
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
The resolver executes on every navigation to the page — a menu link, a `Link` action (including to the same page), or the browser back and forward buttons all re-resolve the content on the server. Dynamic page config is never served from a client cache.
|
|
172
|
+
|
|
173
|
+
## Using pathParams in the Routine
|
|
174
|
+
|
|
175
|
+
On a page with a [`path`](/page-paths), the values of its placeholders are forwarded as `pathParams`, next to `urlQuery`. A page with `path: forms/{form_id}`, loaded as `/forms/F-17`, resolves with `pathParams: { form_id: 'F-17' }`, read with `_payload: pathParams.form_id`. Each set of values gets its own page instance, but a page with a `Dynamic` block still starts fresh on every visit.
|
|
176
|
+
|
|
177
|
+
## Client Bundle Types
|
|
178
|
+
|
|
179
|
+
The client bundle is fixed at build time — resolved content can only use block, action and operator types the build included. Types used on static pages are always available. To use a type that appears _only_ in dynamic content, declare it on the `Dynamic` block:
|
|
180
|
+
|
|
181
|
+
```yaml
|
|
182
|
+
- id: insights
|
|
183
|
+
type: Dynamic
|
|
184
|
+
properties:
|
|
185
|
+
endpointId: resolve_insights
|
|
186
|
+
types:
|
|
187
|
+
blocks:
|
|
188
|
+
- Statistic
|
|
189
|
+
- EChart
|
|
190
|
+
actions:
|
|
191
|
+
- CopyToClipboard
|
|
192
|
+
operators:
|
|
193
|
+
- _number
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
The build bundles declared types into the client. If a routine returns a type that is not in the bundle, resolution fails with a clear error instead of a silently broken page.
|
|
197
|
+
|
|
198
|
+
## Dynamic Blocks Policies
|
|
199
|
+
|
|
200
|
+
A dynamic blocks policy, declared under `policies.dynamicBlocks` in `lowdefy.yaml`, lets a Dynamic block render block config that is stored as data — a form built by a form builder, or config a model generated — within limits the app declares. The policy lists what the content may use. Anything unlisted fails, and the policy is checked twice with the same function: by a `ValidateDynamic` step before the content is stored, and on every page get before the content renders.
|
|
201
|
+
|
|
202
|
+
```yaml
|
|
203
|
+
policies:
|
|
204
|
+
dynamicBlocks:
|
|
205
|
+
- id: generated_form
|
|
206
|
+
blocks:
|
|
207
|
+
- Title
|
|
208
|
+
- Paragraph
|
|
209
|
+
- TextInput
|
|
210
|
+
- Selector
|
|
211
|
+
actions:
|
|
212
|
+
- SetState
|
|
213
|
+
- CallAPI
|
|
214
|
+
operators:
|
|
215
|
+
- _state
|
|
216
|
+
- _eq
|
|
217
|
+
- _if
|
|
218
|
+
endpoints:
|
|
219
|
+
- submit_form_response
|
|
220
|
+
links:
|
|
221
|
+
pages:
|
|
222
|
+
- form_submitted
|
|
223
|
+
origins:
|
|
224
|
+
- https://example.com
|
|
225
|
+
state: form
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
| Key | Default | Meaning |
|
|
229
|
+
| --------------- | --------- | ----------------------------------------------------------------------------------------------------------- |
|
|
230
|
+
| `id` | required | Policy id, referenced by Dynamic blocks and steps. |
|
|
231
|
+
| `blocks` | required | Block types the content may use. `Dynamic` cannot be listed. |
|
|
232
|
+
| `actions` | `[]` | Action types the content may use. |
|
|
233
|
+
| `operators` | `[]` | Client operator names. `_string` allows every `_string` method. `_operator` cannot be listed. |
|
|
234
|
+
| `endpoints` | `[]` | Endpoints a `CallAPI` action in the content may call. |
|
|
235
|
+
| `requests` | `[]` | Page requests a `Request` action may call. The build checks every page that hosts the policy defines them. |
|
|
236
|
+
| `links.pages` | `[]` | Page ids the content may link to. A link by app path, like `/form_submitted`, is matched to its page. |
|
|
237
|
+
| `links.origins` | `[]` | Exact origins (`https://example.com`) the content may link to or load from. |
|
|
238
|
+
| `state` | none | When set, input block ids, `SetState` keys and `_state` reads must sit under this state path. |
|
|
239
|
+
| `html` | `false` | When `false`, no string in the content may contain HTML tag syntax. |
|
|
240
|
+
| `limits` | see below | `depth` (10), `blocks` (500), `bytes` (262144) and `actionsPerEvent` (20). They can be raised, not removed. |
|
|
241
|
+
|
|
242
|
+
Besides the lists, a policy requires literal values wherever the content names a target: `properties`, `style`, events and action lists; the params of `Link`, `CallAPI`, `Request` and `SetState`; every `_state` key; and every `pageId` and URL. URLs must be app paths or use a listed origin — including image sources, markdown links and CSS `url()`. A block's properties schema marks which properties hold a URL (see [Plugins](/plugins-introduction)), so a URL property is checked whatever it is called, such as `Search` `indexUrl` or `QRCode` `icon`; every value no schema marks, including action params and the properties of blocks that mark none, is checked by its key (`url`, `href`, `src`, ...). URLs are read as the browser reads them, so surrounding spaces and embedded tabs or newlines do not hide one.
|
|
243
|
+
|
|
244
|
+
> With `html: false`, an operator that builds strings (`_string`, `_uri`, `_base64`, `_json`) can still assemble HTML at render time from content that passed the check. The build warns when a policy lists one. Leave them out of policies for generated content.
|
|
245
|
+
|
|
246
|
+
### Rendering stored content under a policy
|
|
247
|
+
|
|
248
|
+
Put the policy on the Dynamic block, and return the content through a `ValidateDynamic` step with the same policy. Data stays literal in a Dynamic endpoint (see [Data in the returned config is literal](#data-in-the-returned-config-is-literal)); the blocks of a `ValidateDynamic` step that passed with the block's policy are the one exception.
|
|
249
|
+
|
|
250
|
+
```yaml
|
|
251
|
+
pages:
|
|
252
|
+
- id: form
|
|
253
|
+
type: PageHeaderMenu
|
|
254
|
+
blocks:
|
|
255
|
+
- id: generated
|
|
256
|
+
type: Dynamic
|
|
257
|
+
properties:
|
|
258
|
+
endpointId: get_form_blocks
|
|
259
|
+
policy: generated_form
|
|
260
|
+
- id: submit
|
|
261
|
+
type: Button
|
|
262
|
+
properties:
|
|
263
|
+
title: Submit
|
|
264
|
+
events:
|
|
265
|
+
onClick:
|
|
266
|
+
- id: save
|
|
267
|
+
type: CallAPI
|
|
268
|
+
params:
|
|
269
|
+
endpointId: submit_form_response
|
|
270
|
+
payload:
|
|
271
|
+
answers:
|
|
272
|
+
_state: form
|
|
273
|
+
|
|
274
|
+
api:
|
|
275
|
+
- id: get_form_blocks
|
|
276
|
+
type: InternalApi
|
|
277
|
+
routine:
|
|
278
|
+
- id: get_form
|
|
279
|
+
type: MongoDBFindOne
|
|
280
|
+
connectionId: forms
|
|
281
|
+
properties:
|
|
282
|
+
query:
|
|
283
|
+
_id:
|
|
284
|
+
_payload: urlQuery.formId
|
|
285
|
+
- id: check
|
|
286
|
+
type: ValidateDynamic
|
|
287
|
+
properties:
|
|
288
|
+
policy: generated_form
|
|
289
|
+
blocks:
|
|
290
|
+
_step: get_form.blocks
|
|
291
|
+
- :return:
|
|
292
|
+
blocks:
|
|
293
|
+
_step: check.blocks
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
The policy's types are bundled into the page, so a Dynamic block with `policy` does not declare `properties.types`. Content that breaks the policy at page get renders the fallback, and the log lists each violation.
|
|
297
|
+
|
|
298
|
+
### Checking generated content
|
|
299
|
+
|
|
300
|
+
A generator calls `ValidateDynamic` with `throwOnInvalid: false` and feeds the errors back to the model. Each error has a `path` into the submitted content, a `rule` and a `message`. `DescribeDynamicPolicy` returns what the policy allows, with the properties schema of each block and the params schema of each action and operator, to build the prompt from. See [Validating Dynamic Content As A Routine Step](/lowdefy-api#validating-dynamic-content-as-a-routine-step).
|
|
301
|
+
|
|
302
|
+
## Rules and Limitations
|
|
303
|
+
|
|
304
|
+
- **No `requests` in resolved content.** Request artifacts are written at build time. Resolved blocks reference requests defined statically on the page via `Request` actions, or call endpoints with `CallAPI`.
|
|
305
|
+
- **Nesting is allowed** — resolved content may contain further `Dynamic` blocks, up to 5 levels deep.
|
|
306
|
+
- **Page state resets per visit.** Dynamic pages build a fresh context on every navigation, since the server may resolve different content each time. Keep cross-navigation state in `_global` or `_url_query`.
|
|
307
|
+
- **Endpoint auth always applies.** A public page pointing at a role-protected endpoint renders the fallback for users without the role — useful for role-gated sections.
|
|
308
|
+
- **Data cannot carry operators or be blocks.** Operators in step results, payload or state returned into `:return` fail resolution, and so do blocks and actions that are data, except the blocks of a `ValidateDynamic` step under the block's policy. See [Data in the returned config is literal](#data-in-the-returned-config-is-literal) and [Dynamic Blocks Policies](#dynamic-blocks-policies).
|
|
309
|
+
- **`blockId` namespace is shared.** Resolved blocks share the page's state namespace, so `_state` binds across static and dynamic blocks. Keep blockIds unique, as on any page.
|
|
@@ -66,6 +66,7 @@ The schema for passing actions to Lowdefy events is:
|
|
|
66
66
|
```
|
|
67
67
|
(eventName: (action | control)[])
|
|
68
68
|
(eventName: {
|
|
69
|
+
bubble?: boolean,
|
|
69
70
|
shortcut?: string | string[],
|
|
70
71
|
debounce?: {
|
|
71
72
|
ms?: number,
|
|
@@ -241,6 +242,47 @@ To control the debounce delay, set `debounce.ms` to the number of milliseconds t
|
|
|
241
242
|
type: ActionType2
|
|
242
243
|
```
|
|
243
244
|
|
|
245
|
+
## Nested blocks and event bubbling
|
|
246
|
+
|
|
247
|
+
A click, key press or other browser event starts on the element under the pointer and passes up through every block around it, like a `Button` inside a clickable `Card`, or a clickable `Box` in a `List` row. Lowdefy runs only the innermost event that handles it: once a block with actions for the event fires, the blocks around it skip that same browser event. Clicking the `Button` runs the button's `onClick`, not the card's. A block without an event for the interaction, like a `Paragraph` in the card, passes it on, so clicking the text still runs the card's `onClick`.
|
|
248
|
+
|
|
249
|
+
Set `bubble: true` on the inner event to also run the events of the blocks around it. `bubble` passes the browser event one handler further up; set it again on the outer event to pass it further still.
|
|
250
|
+
|
|
251
|
+
###### Button in a clickable card example:
|
|
252
|
+
```yaml
|
|
253
|
+
- id: order_card
|
|
254
|
+
type: Card
|
|
255
|
+
events:
|
|
256
|
+
onClick:
|
|
257
|
+
- id: open_order
|
|
258
|
+
type: Link
|
|
259
|
+
params: order-detail
|
|
260
|
+
blocks:
|
|
261
|
+
- id: delete_button
|
|
262
|
+
type: Button
|
|
263
|
+
properties:
|
|
264
|
+
title: Delete
|
|
265
|
+
events:
|
|
266
|
+
onClick:
|
|
267
|
+
- id: delete_order
|
|
268
|
+
type: Request
|
|
269
|
+
params: delete_order
|
|
270
|
+
- id: select_button
|
|
271
|
+
type: Button
|
|
272
|
+
properties:
|
|
273
|
+
title: Select and open
|
|
274
|
+
events:
|
|
275
|
+
onClick:
|
|
276
|
+
bubble: true # also runs the card's onClick
|
|
277
|
+
try:
|
|
278
|
+
- id: select_order
|
|
279
|
+
type: SetState
|
|
280
|
+
params:
|
|
281
|
+
selected: true
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Only blocks the browser event passed through, around the block that handled it, are skipped. Other blocks' events are never affected, nor are events that run from actions, requests or timers, or events of a block an action called a method on: a `Table` next to the button, or holding it in its toolbar, still fires `onSelectionChange` after the button's `CallMethod` cleared its selection. Inside an `AgGrid`, clicks on a cell's buttons, links, menus, inputs or selection checkbox fire only that control's event, never `onRowClick` or `onCellClick`.
|
|
285
|
+
|
|
244
286
|
## Keyboard Shortcuts
|
|
245
287
|
|
|
246
288
|
Events can be triggered by keyboard shortcuts. Add a `shortcut` property to an event to bind a key combination — when pressed, the event fires as if the user clicked the block. See the [Keyboard Shortcuts](/keyboard-shortcuts) page for the full shortcut format, common shortcuts, recipes, and more.
|
|
@@ -256,9 +298,11 @@ events:
|
|
|
256
298
|
searchOpen: true
|
|
257
299
|
```
|
|
258
300
|
|
|
259
|
-
## Page
|
|
301
|
+
## Page lifecycle events
|
|
302
|
+
|
|
303
|
+
The first blocks on a page, usually a [`container`](/container) type block, can define page lifecycle events. The page initialization events `onInit` and `onInitAsync` are triggered when the page is first loaded, and the browser lifecycle events `onVisible`, `onHidden`, `onOnline`, `onOffline` and `onResize` are triggered while the page stays open. All blocks have `onMount` and `onMountAsync` events, that can be used to initialize the page or blocks.
|
|
260
304
|
|
|
261
|
-
|
|
305
|
+
### Page initialization events
|
|
262
306
|
|
|
263
307
|
The `onInit` event is triggered the first time a page is loaded. This event blocks page render, in other words, the page __will__ remain in a loading state, rendering only the progress bar, until all the actions have completed execution. It can be used to set up [`state`](/page-and-app-state). Actions that take a long time to execute, like `Request`, should be used sparingly here for a better user experience.
|
|
264
308
|
|
|
@@ -268,6 +312,108 @@ The `onMount` event is triggered every time a block is rendered on a page. This
|
|
|
268
312
|
|
|
269
313
|
The `onMountAsync` event is triggered every time a block is mounted, but does not render the block in loading.
|
|
270
314
|
|
|
315
|
+
### Browser lifecycle events
|
|
316
|
+
|
|
317
|
+
The first blocks on a page can also define events that react to the browser: `onVisible`, `onHidden`, `onOnline`, `onOffline` and `onResize`. These are useful to refresh data that went stale while the user was away, instead of polling the server on a timer.
|
|
318
|
+
|
|
319
|
+
These events are only attached while the page is mounted, and are removed again when the user navigates away, so they never trigger for a page the user has left. They never trigger on the initial page load either — only a change after the page has loaded triggers them. Their action chains run like `onMountAsync`: they do not keep the page or block in a loading state.
|
|
320
|
+
|
|
321
|
+
The `onVisible` event is triggered when the browser tab becomes visible again, or when the window regains focus. Rapid pairs of these signals — a tab switch usually produces both — are coalesced over 300ms, so the event is only triggered once. The [`_event`](/_event) object contains `visible: true` and `reason`, which is `visibility` when the browser reported the tab becoming visible, or `focus` when the window regained focus.
|
|
322
|
+
|
|
323
|
+
```yaml
|
|
324
|
+
events:
|
|
325
|
+
onVisible:
|
|
326
|
+
- id: refresh_tasks
|
|
327
|
+
type: Request
|
|
328
|
+
params: get_tasks
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
The `onHidden` event is triggered when the browser tab is hidden, or when the window loses focus, coalesced in the same way. The `_event` object contains `visible: false` and the same `reason` field.
|
|
332
|
+
|
|
333
|
+
```yaml
|
|
334
|
+
events:
|
|
335
|
+
onHidden:
|
|
336
|
+
- id: stop_refreshing
|
|
337
|
+
type: SetState
|
|
338
|
+
params:
|
|
339
|
+
live: false
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
The `onOnline` and `onOffline` events are triggered when the browser reports that the network connection was regained or lost. The `_event` object contains `online: true` or `online: false`.
|
|
343
|
+
|
|
344
|
+
```yaml
|
|
345
|
+
events:
|
|
346
|
+
onOnline:
|
|
347
|
+
- id: back_online
|
|
348
|
+
type: Message
|
|
349
|
+
params:
|
|
350
|
+
content: You are back online.
|
|
351
|
+
onOffline:
|
|
352
|
+
- id: went_offline
|
|
353
|
+
type: Message
|
|
354
|
+
params:
|
|
355
|
+
status: warning
|
|
356
|
+
content: You are offline, changes will not be saved.
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
The `onResize` event is triggered when the window is resized, debounced by 150ms so that the actions only run once the user stops resizing. Blocks that use the [`_media`](/_media) operator are re-evaluated for the new window size before the `onResize` actions run. The `_event` object contains the `width` and `height` of the window.
|
|
360
|
+
|
|
361
|
+
```yaml
|
|
362
|
+
events:
|
|
363
|
+
onResize:
|
|
364
|
+
- id: set_width
|
|
365
|
+
type: SetState
|
|
366
|
+
params:
|
|
367
|
+
window_width:
|
|
368
|
+
_event: width
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
## App events
|
|
372
|
+
|
|
373
|
+
Events can also be defined for the whole app, in the `events` object at the root of `lowdefy.yaml`. App events run once each time the app is loaded in the browser, whichever page is opened first, and do not run again when the user navigates between pages. Opening the app in a new tab, or reloading the browser, loads the app again. App events are a good place to set up [`global`](/page-and-app-state) values that every page uses, like user settings fetched from an [API endpoint](/lowdefy-api).
|
|
374
|
+
|
|
375
|
+
- `onInit`: Runs before the first page's own events. The page stays in its loading state, rendering only the progress bar, until the app `onInit` actions have finished, so the first page's `onInit` can read the values it set with [`_global`](/_global).
|
|
376
|
+
- `onInitAsync`: Runs once the app `onInit` has finished, without blocking the page. The first page's events do not wait for it, and pages re-render when it sets `global` values.
|
|
377
|
+
|
|
378
|
+
###### Load user settings when the app loads:
|
|
379
|
+
```yaml
|
|
380
|
+
# lowdefy.yaml
|
|
381
|
+
global:
|
|
382
|
+
settings: null
|
|
383
|
+
events:
|
|
384
|
+
onInit:
|
|
385
|
+
- id: set_user
|
|
386
|
+
type: SetGlobal
|
|
387
|
+
params:
|
|
388
|
+
userName:
|
|
389
|
+
_user: name
|
|
390
|
+
onInitAsync:
|
|
391
|
+
try:
|
|
392
|
+
- id: fetch_settings
|
|
393
|
+
type: CallAPI
|
|
394
|
+
params:
|
|
395
|
+
endpointId: user_settings
|
|
396
|
+
- id: set_settings
|
|
397
|
+
type: SetGlobal
|
|
398
|
+
params:
|
|
399
|
+
settings:
|
|
400
|
+
_actions: fetch_settings.response.response
|
|
401
|
+
catch:
|
|
402
|
+
- id: warn
|
|
403
|
+
type: DisplayMessage
|
|
404
|
+
params:
|
|
405
|
+
content: Could not load your settings.
|
|
406
|
+
status: warning
|
|
407
|
+
pages:
|
|
408
|
+
# ...
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
App events run outside any page, so page state, inputs, requests, blocks and subscriptions are not available to them. The build fails if an app event uses the `CallMethod`, `Request`, `Reset`, `ResetValidation`, `SetFocus`, `SetState`, `Subscribe`, `Unsubscribe` or `Validate` actions, or the `_input`, `_request`, `_request_details`, `_state` or `_websocket` operators. Use [`CallAPI`](/CallAPI) to fetch data, [`SetGlobal`](/SetGlobal) to store it, and operators like [`_user`](/_user), [`_url_query`](/_url_query), [`_global`](/_global) and [`_actions`](/_actions) to read values. A [`Link`](/Link) action can redirect the user, for example to an onboarding page.
|
|
412
|
+
|
|
413
|
+
App event errors are handled like page event errors: the error message is displayed, the error is logged, and the `catch` actions run. A failed app `onInit` does not stop the page from loading, and the app `onInitAsync` still runs after it. App events do not support `shortcut`.
|
|
414
|
+
|
|
415
|
+
The app events config is sent to the browser with the rest of the app config, like `global`, so do not put secrets in it.
|
|
416
|
+
|
|
271
417
|
## Action types
|
|
272
418
|
|
|
273
419
|
The following actions can be used:
|
|
@@ -295,8 +441,14 @@ See additional action type available under the Actions tab in the menu.
|
|
|
295
441
|
- The [`_actions`](/_actions) operator is available for sequential actions to use the values returned from preceding actions in the chain.
|
|
296
442
|
- Actions have a `skip` field that can be used to skip action execution.
|
|
297
443
|
- Action lists also support the [`:if`](/:if), [`:switch`](/:switch) and [`:return`](/:return) controls — `skip` gates one action, `:if` gates a group, `:switch` picks between alternatives, and `:return` ends the event early.
|
|
444
|
+
- A browser event runs only the innermost block event that handles it. Set `bubble: true` on an event to also run the events of the blocks around it.
|
|
298
445
|
- Events support `shortcut` to bind keyboard shortcuts to the event. The shortcut fires the event when the key combination is pressed.
|
|
299
446
|
- The `onInit` event is triggered the first time a page is mounted and keeps the page in loading until all actions have finished.
|
|
300
447
|
- The `onInitAsync` event is triggered the first time a page is mounted and does not keep the page in loading.
|
|
301
448
|
- The `onMount` events is triggered the every time a block is mounted and keeps the block in loading until all actions have finished.
|
|
302
449
|
- The `onMountAsync` event is triggered the every time a block is mounted, after `onMount` has completed, and does not keep the block in loading.
|
|
450
|
+
- The `onVisible` and `onHidden` events are triggered when the browser tab is shown or hidden, or when the window gains or loses focus, coalesced over 300ms.
|
|
451
|
+
- The `onOnline` and `onOffline` events are triggered when the browser reports that the network connection was regained or lost.
|
|
452
|
+
- The `onResize` event is triggered when the window is resized, debounced by 150ms.
|
|
453
|
+
- Browser lifecycle events are never triggered on the initial page load, and are removed when the user navigates away from the page.
|
|
454
|
+
- App events, defined in the root `events` object, run once per app load: the app `onInit` runs before the first page's events and keeps the page in loading, and the app `onInitAsync` runs after it without blocking the page.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# The Four Primitives
|
|
2
|
+
|
|
3
|
+
Every Lowdefy app is composed from four primitives. Learn these four ideas and you can read any Lowdefy app.
|
|
4
|
+
|
|
5
|
+
What the user sees. React components — inputs, tables, charts, containers — arranged into pages.
|
|
6
|
+
|
|
7
|
+
How the app thinks. Functions written in config that read state and shape data, re-evaluated on every change.
|
|
8
|
+
|
|
9
|
+
What happens next. Event handlers that run when users click, pages load, or values change.
|
|
10
|
+
|
|
11
|
+
Where the data lives. Server-side integrations to databases, APIs, and services, called through requests.
|
|
12
|
+
|
|
13
|
+
## How they fit together
|
|
14
|
+
|
|
15
|
+
A page is a tree of **blocks**. Blocks hold values in page **state** — a `TextInput` writes what the user types, a `Selector` writes the chosen option.
|
|
16
|
+
|
|
17
|
+
**Operators** are functions evaluated in config. They read state and context — `_state`, `_user`, `_media` — and compute the values around them: a block's visibility, a title's text, a request's query. When state changes, operators re-evaluate and the page updates.
|
|
18
|
+
|
|
19
|
+
User interaction fires **events** — a click, a page load, an input change. Each event runs a list of **actions**: `SetState` writes state, `Link` navigates, `Request` calls the server.
|
|
20
|
+
|
|
21
|
+
**Connections** define the services your app talks to — a database, an HTTP API, an AI provider. **Requests** execute against them on the server, so credentials never reach the browser. Actions trigger requests; operators read their results.
|
|
22
|
+
|
|
23
|
+
One loop, four primitives: blocks render state → events fire actions → actions set state and call requests → operators re-evaluate → blocks re-render.
|
|
24
|
+
|
|
25
|
+
## Where to go deeper
|
|
26
|
+
|
|
27
|
+
- [Blocks](/blocks) — the block object and the page tree.
|
|
28
|
+
- [Operators](/operators) — evaluation rules and where operators work.
|
|
29
|
+
- [Events and Actions](/events-and-actions) — event chains, error handling.
|
|
30
|
+
- [Connections and Requests](/connections-and-requests) — the server-side model.
|
|
31
|
+
- Or see everything in the [Reference](/reference).
|