@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
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
# Page and App State
|
|
2
|
+
|
|
3
|
+
A Lowdefy app has a few different data objects which can be accessed and modified. The app wide objects are the `global`, `media` and `user` objects. Then there are page specific objects like the `state`, `urlQuery`, `pathParams` and `input` objects.
|
|
4
|
+
|
|
5
|
+
## State
|
|
6
|
+
|
|
7
|
+
Each page in a Lowdefy app has a `state` object which serves as the general data store for that page.
|
|
8
|
+
|
|
9
|
+
Every [`input` category block](/blocks) inside the page will have a value in the `state` object, with their `id` as the key in the `state` object. If the block is not visible the input value is removed from the state object.
|
|
10
|
+
|
|
11
|
+
The [`_state`](/_state) operator can be used to read from `state` and the [`SetState`](/SetState) action can be used to modify or add new values in `state` object in the same page from which `SetState` is called.
|
|
12
|
+
|
|
13
|
+
> See [`operators`](/operators) and [`events-and-actions`](/events-and-actions) for more details.
|
|
14
|
+
|
|
15
|
+
Page states remain even as users navigate to new pages - so if a user returns to a page, the state as they left it will remain.
|
|
16
|
+
|
|
17
|
+
### Reading from state
|
|
18
|
+
Here is an example showing how to read `input` block values from `state`:
|
|
19
|
+
```yaml
|
|
20
|
+
id: my-page
|
|
21
|
+
type: PageHeaderMenu
|
|
22
|
+
blocks:
|
|
23
|
+
- id: Name
|
|
24
|
+
type: TextInput
|
|
25
|
+
- id: Age
|
|
26
|
+
type: NumberInput
|
|
27
|
+
- id: MyDisplay
|
|
28
|
+
type: Html
|
|
29
|
+
properties:
|
|
30
|
+
html:
|
|
31
|
+
_string.concat:
|
|
32
|
+
- <b>Name:</b>
|
|
33
|
+
- _state: Name
|
|
34
|
+
- <br/><b>Age:</b>
|
|
35
|
+
- _state: Age
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Modifying state
|
|
39
|
+
The following examples demonstrates how to modify `state`:
|
|
40
|
+
```yaml
|
|
41
|
+
id: my-page
|
|
42
|
+
type: PageHeaderMenu
|
|
43
|
+
blocks:
|
|
44
|
+
- id: Name
|
|
45
|
+
type: TextInput
|
|
46
|
+
- id: Age
|
|
47
|
+
type: NumberInput
|
|
48
|
+
- id: Button
|
|
49
|
+
type: Button
|
|
50
|
+
events:
|
|
51
|
+
onClick:
|
|
52
|
+
- id: set_person_object
|
|
53
|
+
type: SetState
|
|
54
|
+
params:
|
|
55
|
+
person:
|
|
56
|
+
name:
|
|
57
|
+
_state: Name
|
|
58
|
+
age:
|
|
59
|
+
_state: Age
|
|
60
|
+
example: true
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
This will result in a `state` which looks like:
|
|
64
|
+
```json5
|
|
65
|
+
{
|
|
66
|
+
"Name": "Alice", // The TextInput value
|
|
67
|
+
"Age": 99, //The NumberInput value
|
|
68
|
+
"person": {
|
|
69
|
+
"name": "Alice",
|
|
70
|
+
"age": 99,
|
|
71
|
+
"example": true
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Global
|
|
77
|
+
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 page. The `global` object can be modified using the [`SetGlobal`](/SetGlobal) action.
|
|
78
|
+
|
|
79
|
+
> Note that when `SetGlobal` is called, `global` will not be consistent between clients, like different users, or a single user with multiple tabs open.
|
|
80
|
+
|
|
81
|
+
### Reading from global
|
|
82
|
+
This example shows how you can create and read from `global`:
|
|
83
|
+
|
|
84
|
+
`lowdefy.yaml`
|
|
85
|
+
```yaml
|
|
86
|
+
lowdefy: 7.0.0
|
|
87
|
+
global:
|
|
88
|
+
key: value
|
|
89
|
+
pages:
|
|
90
|
+
- id: my-page
|
|
91
|
+
type: PageSiderMenu
|
|
92
|
+
blocks:
|
|
93
|
+
id: DisplayGlobalKey
|
|
94
|
+
type: Html
|
|
95
|
+
html:
|
|
96
|
+
_global: key ## Returns 'value'
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Modifying global
|
|
100
|
+
The following examples shows how to modify the `global` object:
|
|
101
|
+
|
|
102
|
+
`lowdefy.yaml`
|
|
103
|
+
```yaml
|
|
104
|
+
lowdefy: 7.0.0
|
|
105
|
+
global:
|
|
106
|
+
key: value
|
|
107
|
+
pages:
|
|
108
|
+
- id: my-page
|
|
109
|
+
type: PageSiderMenu
|
|
110
|
+
blocks:
|
|
111
|
+
- id: DisplayGlobalKey
|
|
112
|
+
type: Html
|
|
113
|
+
html:
|
|
114
|
+
_global: key ## Returns `value`
|
|
115
|
+
- id: ModifyGlobal
|
|
116
|
+
type: Button
|
|
117
|
+
events:
|
|
118
|
+
onClick:
|
|
119
|
+
- id: modify_global_key
|
|
120
|
+
type: SetGlobal
|
|
121
|
+
params:
|
|
122
|
+
key: New Value
|
|
123
|
+
- id: DisplayModifiedGlobalKey
|
|
124
|
+
type: Html
|
|
125
|
+
html:
|
|
126
|
+
_global: key ## Returns `New Value`
|
|
127
|
+
```
|
|
128
|
+
## URL query
|
|
129
|
+
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 and read using the [`_url_query`](/_url_query) operator. 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 [`onMount`](/events-and-actions) event.
|
|
130
|
+
|
|
131
|
+
> Note that any variables set to `urlQuery` will be visible to users of the app.
|
|
132
|
+
|
|
133
|
+
### Example using `urlQuery` and `Link`
|
|
134
|
+
|
|
135
|
+
`first-page.yaml`
|
|
136
|
+
```yaml
|
|
137
|
+
id: first-page
|
|
138
|
+
type: PageSiderMenu
|
|
139
|
+
blocks:
|
|
140
|
+
- id: LinkButton
|
|
141
|
+
type: Button
|
|
142
|
+
events:
|
|
143
|
+
- id: link_to_second_page
|
|
144
|
+
type: Link
|
|
145
|
+
params:
|
|
146
|
+
pageId: second-page
|
|
147
|
+
urlQuery:
|
|
148
|
+
document-id: ABC123
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
`second-page.yaml`
|
|
152
|
+
```yaml
|
|
153
|
+
id: second-page
|
|
154
|
+
type: PageSiderMenu
|
|
155
|
+
events:
|
|
156
|
+
onMount:
|
|
157
|
+
- id: set_url_id
|
|
158
|
+
type: SetState
|
|
159
|
+
params:
|
|
160
|
+
myDocId:
|
|
161
|
+
_url_query: document-id ## Returns 'ABC123'
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Path parameters
|
|
165
|
+
|
|
166
|
+
A page with a [`path`](/page-paths), like `tickets/{space}/{ticket_id}`, is opened at a URL that holds the values of its placeholders, like `/tickets/support/1234`. The `pathParams` object holds these values, `{ space: 'support', ticket_id: '1234' }`. They are set with the `pathParams` field of the [`Link`](/Link) action and read with the [`_path_params`](/_path_params) operator. Unlike `urlQuery` values, path parameters are always strings, and every placeholder always has one.
|
|
167
|
+
|
|
168
|
+
A page with placeholders has one instance for each set of values, each with its own `state`, `input` and request results, so ticket 1's state never shows on ticket 2. See [Page instances](/page-paths#page-instances).
|
|
169
|
+
|
|
170
|
+
> Note that path parameters, like `urlQuery` values, are visible to users of the app and can be changed by them.
|
|
171
|
+
|
|
172
|
+
## Input
|
|
173
|
+
|
|
174
|
+
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. Variables set to the `input` object are not written to the URL, so they are not visible to app users but also cannot be used to share the data in a link since a `input` object is only consistent between one page and the next to which it links. A `input` object is set using the `input` param of the [`Link`](/Link) action or the `input` property of an [`Anchor`](/Anchor) block when linking from a page to another page in the app and can be read using the [`_input`](/_input) operator.
|
|
175
|
+
|
|
176
|
+
> Note `input` cannot be passed between pages when using the `newTab: true` param in the [`Link`](/Link) action.
|
|
177
|
+
|
|
178
|
+
### Example of setting and reading `input`
|
|
179
|
+
|
|
180
|
+
`first-page.yaml`
|
|
181
|
+
```yaml
|
|
182
|
+
id: first-page
|
|
183
|
+
type: PageSiderMenu
|
|
184
|
+
blocks:
|
|
185
|
+
- id: LinkButton
|
|
186
|
+
type: Button
|
|
187
|
+
events:
|
|
188
|
+
- id: link_to_second_page
|
|
189
|
+
type: Link
|
|
190
|
+
params:
|
|
191
|
+
pageId: second-page
|
|
192
|
+
input:
|
|
193
|
+
document-id: 1234
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
`second-page.yaml`
|
|
197
|
+
```yaml
|
|
198
|
+
id: second-page
|
|
199
|
+
type: PageSiderMenu
|
|
200
|
+
events:
|
|
201
|
+
onMount:
|
|
202
|
+
- id: set_input_id
|
|
203
|
+
type: SetState
|
|
204
|
+
params:
|
|
205
|
+
myDocId:
|
|
206
|
+
_input: document-id ## Returns '1234'
|
|
207
|
+
```
|
|
208
|
+
## Media
|
|
209
|
+
|
|
210
|
+
The `media` object contains some information about the client screen size, and can be accessed using the [`_media`](/_media) operator. This can be used to add additional responsive logic to a page. When the window is resized, blocks that read a `media` value that changed are re-evaluated once the resize settles.
|
|
211
|
+
|
|
212
|
+
Here is an example showing how to read the screen size of a smartphone:
|
|
213
|
+
```yaml
|
|
214
|
+
id: DisplayScreenSize
|
|
215
|
+
type: Html
|
|
216
|
+
properties:
|
|
217
|
+
html:
|
|
218
|
+
_media: size ## Returns xs if used on phone width screen width < 640px
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
## User
|
|
222
|
+
|
|
223
|
+
If authentication is configured and a user is logged in, data about the user can be accessed using the [`_user`](/_user) operator. See [User Authentication](/users-introduction) for more details.
|
|
224
|
+
|
|
225
|
+
This example shows how to read a logged-in user's username and id:
|
|
226
|
+
```yaml
|
|
227
|
+
id: my-page
|
|
228
|
+
type: PageSiderMenu
|
|
229
|
+
blocks:
|
|
230
|
+
- id: DisplayUserName
|
|
231
|
+
type: Html
|
|
232
|
+
properties:
|
|
233
|
+
html:
|
|
234
|
+
_string.concat:
|
|
235
|
+
- <b>Name: </b>
|
|
236
|
+
- _user: name
|
|
237
|
+
- id: DisplayUserId
|
|
238
|
+
type: Html
|
|
239
|
+
properties:
|
|
240
|
+
html:
|
|
241
|
+
_string.concat:
|
|
242
|
+
- <b>ID: </b>
|
|
243
|
+
- _user: id
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
#### TLDR
|
|
247
|
+
- There are app wide and page specific data objects.
|
|
248
|
+
- App wide are `global`, `media` and `user`.
|
|
249
|
+
- Page specific are `state`, `urlQuery`, `pathParams` and `input`.
|
|
250
|
+
- All input blocks write their value to `state`, with the their `id` as the key in the `state` object.
|
|
251
|
+
- Input blocks which are not visible are removed from `state`.
|
|
252
|
+
- The `SetState` action can also modify the `state` object.
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
# Page Paths
|
|
2
|
+
|
|
3
|
+
A page is served at its `id` by default: a page with id `ticket` is at `/ticket`, and the record it shows is passed in the query string, like `/ticket?ticket_id=1234`. Set a page's `path` to give it an address of its own, with placeholders for the values that say which record it shows:
|
|
4
|
+
|
|
5
|
+
```yaml
|
|
6
|
+
pages:
|
|
7
|
+
- id: ticket
|
|
8
|
+
path: tickets/{space}/{ticket_id}
|
|
9
|
+
type: PageHeaderMenu
|
|
10
|
+
blocks:
|
|
11
|
+
- id: title
|
|
12
|
+
type: Title
|
|
13
|
+
properties:
|
|
14
|
+
content:
|
|
15
|
+
_string.concat:
|
|
16
|
+
- 'Ticket '
|
|
17
|
+
- _path_params: ticket_id
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The page is now served at `/tickets/support/1234`, and [`_path_params`](/_path_params) reads `support` and `1234` from the URL. A page without `path` is served at its id, as before.
|
|
21
|
+
|
|
22
|
+
The `id` stays the page's identity. [`auth.pages`](/protected-pages-apis), menus, the `Link` action's `pageId`, [`_module.pageId`](/_module), `_location: pageId`, requests and agents all name the page by its id. Only the URL changes.
|
|
23
|
+
|
|
24
|
+
## Writing a path
|
|
25
|
+
|
|
26
|
+
A `path` is written like a page id: no leading or trailing `/`, with segments separated by `/`. Each segment is either:
|
|
27
|
+
|
|
28
|
+
- fixed text, using the characters a page id may use (`A-Z`, `a-z`, `0-9`, `-`, `_` and `:`), or
|
|
29
|
+
- a placeholder, `{name}`, filling the whole segment. A name starts with a letter or `_` and only contains `A-Z`, `a-z`, `0-9` and `_`. Each name appears once in a path.
|
|
30
|
+
|
|
31
|
+
Placeholders can go in any segment, the first included. A `path` without placeholders is allowed too, and serves the page at that address instead of its id.
|
|
32
|
+
|
|
33
|
+
These are not supported, and the build fails on them:
|
|
34
|
+
|
|
35
|
+
- A placeholder inside a segment, like `ticket-{id}`.
|
|
36
|
+
- Optional placeholders, like `{id?}`.
|
|
37
|
+
- Catch-all placeholders, like `{...rest}`.
|
|
38
|
+
|
|
39
|
+
### Quote a path that starts with a placeholder
|
|
40
|
+
|
|
41
|
+
In YAML, a value that starts with `{` is read as an object, so a path that starts with a placeholder must be quoted:
|
|
42
|
+
|
|
43
|
+
```yaml
|
|
44
|
+
pages:
|
|
45
|
+
- id: space-ticket
|
|
46
|
+
path: '{space}/tickets/{ticket_id}'
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Unquoted, `path: {space}/tickets/{ticket_id}` fails to parse, and `path: {slug}` parses as an object with no error from YAML. The build checks that `path` is a string and tells you to quote it.
|
|
50
|
+
|
|
51
|
+
### Pages in modules
|
|
52
|
+
|
|
53
|
+
A module page's `path` is prefixed with its module entry id, as its `id` is. A module page with `path: '{space}/tickets/{ticket_id}'`, in a module entry with id `support`, is served at `/support/{space}/tickets/{ticket_id}`. Since the entry id is a fixed first segment, module pages always outrank app pages whose path starts with a placeholder.
|
|
54
|
+
|
|
55
|
+
### Pages the framework links to
|
|
56
|
+
|
|
57
|
+
Some pages are reached at an address Lowdefy writes for you, with no values to fill placeholders, so these pages cannot have them:
|
|
58
|
+
|
|
59
|
+
- **The home page.** The `config.homePageId` page is served at `/`, so it cannot have placeholders. When `homePageId` is not set, home is the first menu link the user may see. A menu link to a page with placeholders must give their values in `pathParams` (see [Menus](/menus)), and home then opens that page with those values.
|
|
60
|
+
- **Auth pages.** The pages in `auth.authPages`, such as the sign-in page, are redirect targets and cannot have placeholders. When an auth page has a `path`, set its `authPages` URL to that path (`/` and the path), since nothing is served at its id.
|
|
61
|
+
- **The `404` page.** The `404` page cannot have a `path` at all. Every URL that matches no page is redirected to `/404`.
|
|
62
|
+
|
|
63
|
+
## Linking to a page with a path
|
|
64
|
+
|
|
65
|
+
Link to a page by its `pageId`, and give the placeholder values in `pathParams`, next to `urlQuery`:
|
|
66
|
+
|
|
67
|
+
```yaml
|
|
68
|
+
- id: open_ticket
|
|
69
|
+
type: Link
|
|
70
|
+
params:
|
|
71
|
+
pageId: ticket
|
|
72
|
+
pathParams:
|
|
73
|
+
space: support
|
|
74
|
+
ticket_id:
|
|
75
|
+
_state: ticket_id
|
|
76
|
+
urlQuery:
|
|
77
|
+
tab: comments
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
This opens `/tickets/support/1234?tab=comments`. Lowdefy builds the URL from the page's path, adds the app's `basePath` and encodes each value, so a value can hold any character, `/` included.
|
|
81
|
+
|
|
82
|
+
`pathParams` works wherever a page link is written:
|
|
83
|
+
|
|
84
|
+
- The [`Link`](/Link) action, and the `callbackUrl` of the auth actions, like [`Login`](/Login), [`Logout`](/Logout), [`MagicLinkVerify`](/MagicLinkVerify) and [`EmailOtpVerify`](/EmailOtpVerify).
|
|
85
|
+
- [Menu links](/menus). A menu link's `pathParams` must be literal strings, since menus are built once for the app.
|
|
86
|
+
- HTML links, with the `data-path-params` attribute next to `data-page-id` (see [HTML attributes](/html-attributes#links)).
|
|
87
|
+
- Table and grid cell links and row links in [`Table`](/Table), [`TableLight`](/TableLight) and [`AgGrid`](/AgGrid), where each `pathParams` value is a field path in the row, as `urlQuery` values are there: `link: { pageId: ticket, pathParams: { space: space_id, ticket_id: _id } }`.
|
|
88
|
+
- The [`Anchor`](/Anchor) block.
|
|
89
|
+
- [Notification and email links](/notifications#links).
|
|
90
|
+
|
|
91
|
+
The rules for values:
|
|
92
|
+
|
|
93
|
+
- Values are strings. A number is converted with `String()`, so `1234` gives `"1234"`.
|
|
94
|
+
- Every placeholder needs a value. A missing, `null` or empty value fails the link with an error naming the page and the placeholder.
|
|
95
|
+
- A value cannot be `.` or `..`. Browsers drop those segments from a URL before the request is sent, so no link could reach the page. Values that contain dots, like `v1.2`, are fine.
|
|
96
|
+
- Keys the path does not use are ignored.
|
|
97
|
+
- Values never merge into `urlQuery`. A page can have a `space` placeholder and a `space` query value, and each is read with its own operator.
|
|
98
|
+
|
|
99
|
+
The build checks the links it can read: a `Link` action with a literal `pageId`, an HTML `data-page-id` link and a menu link must give a value for every placeholder of the page they link to. Values computed by operators, and links in block properties such as table cells, are checked when the link is used.
|
|
100
|
+
|
|
101
|
+
### Block property links on public pages
|
|
102
|
+
|
|
103
|
+
The browser only knows the paths of the pages the user may open, and of the pages the current page links to with a `Link` action or an HTML `data-page-id` link. Links in block properties, like `Anchor` and table or grid cells, and links in app events are not collected. On a public page, such a link to a protected page with a path cannot be built for a logged-out user, and fails. Use a `Link` action or an HTML link there instead: the logged-out user is then sent to sign in, and returned to the page afterwards.
|
|
104
|
+
|
|
105
|
+
## Reading the values
|
|
106
|
+
|
|
107
|
+
- [`_path_params`](/_path_params) reads the values in a page, with the same `key`, `all` and `default` arguments as [`_url_query`](/_url_query).
|
|
108
|
+
- In a [`_js`](/_js) function, `pathParams('ticket_id')` does the same.
|
|
109
|
+
- An action plugin reads them with `getPathParams`, as it reads the query with `getUrlQuery` (see [Action plugins](/plugins-actions)).
|
|
110
|
+
- [Dynamic page content](/dynamic-page-content) endpoints receive them as `pathParams` in the payload, next to `urlQuery`.
|
|
111
|
+
- An [agent](/agent-properties) receives them as `pathParams` when the [`AgentChat`](/AgentChat) block is on a page with a path, and includes them in its page context.
|
|
112
|
+
|
|
113
|
+
Requests run on the server and cannot read the URL. Pass the values to a request in its `payload`:
|
|
114
|
+
|
|
115
|
+
```yaml
|
|
116
|
+
requests:
|
|
117
|
+
- id: get_ticket
|
|
118
|
+
type: MongoDBFindOne
|
|
119
|
+
connectionId: tickets
|
|
120
|
+
payload:
|
|
121
|
+
space:
|
|
122
|
+
_path_params: space
|
|
123
|
+
ticket_id:
|
|
124
|
+
_path_params: ticket_id
|
|
125
|
+
properties:
|
|
126
|
+
query:
|
|
127
|
+
space:
|
|
128
|
+
_payload: space
|
|
129
|
+
ticket_id:
|
|
130
|
+
_payload: ticket_id
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## How URLs match pages
|
|
134
|
+
|
|
135
|
+
When a URL is requested, Lowdefy compares its segments with every page path that has the same number of segments. Pages without a `path` take part with their id, as all-fixed paths. When more than one path matches, they are compared from left to right, and at the first segment where they differ, a fixed segment beats a placeholder.
|
|
136
|
+
|
|
137
|
+
For example, with these three pages:
|
|
138
|
+
|
|
139
|
+
```yaml
|
|
140
|
+
pages:
|
|
141
|
+
- id: space-tickets
|
|
142
|
+
path: '{space}/tickets'
|
|
143
|
+
- id: admin-section
|
|
144
|
+
path: admin/{section}
|
|
145
|
+
- id: admin/tickets
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
- `/support/tickets` opens `space-tickets`, with `space` set to `support`.
|
|
149
|
+
- `/admin/users` opens `admin-section`, with `section` set to `users`.
|
|
150
|
+
- `/admin/tickets` opens the `admin/tickets` page. All three paths match, and the fixed `admin` beats `{space}` in the first segment, then the fixed `tickets` beats `{section}` in the second.
|
|
151
|
+
|
|
152
|
+
The order of pages in your config never changes which page a URL opens.
|
|
153
|
+
|
|
154
|
+
**Ties.** Two paths tie when they have the same number of segments, placeholders in the same positions, and the same fixed segments, ignoring case. `tickets/{id}` and `tickets/{ticket_id}` tie, as do `Tickets/{id}` and `tickets/{id}`. The build fails on a tie and names both pages.
|
|
155
|
+
|
|
156
|
+
**Case.** Matching is case-sensitive: `/Tickets/support/1234` does not open `tickets/{space}/{ticket_id}`. Values keep their case.
|
|
157
|
+
|
|
158
|
+
**Slashes.** One trailing `/` is ignored. A URL with an empty segment, like `/tickets//1234`, matches no page, so a missing value can never shift the other values into a shorter path. A segment that is `.` or `..`, encoded or not, matches no page either.
|
|
159
|
+
|
|
160
|
+
**Encoding.** Each segment is decoded before it is matched, so `%2F` in a URL gives a value that contains `/`, and `a+b` and `a%2Bb` give the same value.
|
|
161
|
+
|
|
162
|
+
### Values that other addresses take first
|
|
163
|
+
|
|
164
|
+
A placeholder matches any value, but some values reach something else first. This matters most for a path that starts with a placeholder, like `{space}/tickets/{ticket_id}`:
|
|
165
|
+
|
|
166
|
+
- **A fixed segment of another page.** If `admin/tickets/new` is a page, a space named `admin` cannot reach `{space}/tickets/new`. The build cannot see your data, so it cannot catch this.
|
|
167
|
+
- **`.well-known`**, always.
|
|
168
|
+
- **`404`**, the not-found page.
|
|
169
|
+
- **`api`**, where the rest of the URL is a Lowdefy API route, like `/api/page/...` or `/api/request/...`. Other `/api/...` URLs reach the pages.
|
|
170
|
+
- **Static files.** A URL where a file exists in the app's `public` folder, or a built asset under `/assets`, serves the file.
|
|
171
|
+
- **In development**, the dev server's own addresses: `/lowdefy-docs`, and the paths that start with `client`, `lib`, `build`, `node_modules` or `@`, and `/favicon.ico`.
|
|
172
|
+
|
|
173
|
+
An app that starts a path with a placeholder should keep its values clear of these names.
|
|
174
|
+
|
|
175
|
+
## Page instances
|
|
176
|
+
|
|
177
|
+
A page with placeholders has one instance for each set of values. Each instance has its own state, request results and input, and runs its own `onInit`. Opening ticket 2 after ticket 1 starts a fresh page, and going back to ticket 1 finds it as the user left it.
|
|
178
|
+
|
|
179
|
+
- Each page keeps its 10 most recently used instances. When an 11th is opened, the least recently used one is dropped, and opening it again is a first visit.
|
|
180
|
+
- Changing only the query string, for example with a `Link` action that updates `urlQuery`, stays on the same instance.
|
|
181
|
+
- Two URLs that decode to the same values, like `/tickets/a+b` and `/tickets/a%2Bb`, open the same instance.
|
|
182
|
+
- A page with a [`Dynamic`](/dynamic-page-content) block keeps no state between visits, as before. Each visit starts fresh.
|
|
183
|
+
- A page without placeholders has one instance, as every page did before.
|
|
184
|
+
|
|
185
|
+
As on any page, `onInit` runs once per instance and `onMount` every time it is shown. Load data that must be up to date each time the user returns to a record in `onMount`, and set up state that should survive a trip away and back in `onInit`.
|
|
186
|
+
|
|
187
|
+
Menu highlighting follows the page id, so every ticket highlights the menu link to the ticket page.
|
|
188
|
+
|
|
189
|
+
## Security
|
|
190
|
+
|
|
191
|
+
Path values are as user-controlled as the query string. Anyone can type a different value into the URL.
|
|
192
|
+
|
|
193
|
+
> **DO NOT** put any private or personal information in a path; all values in a URL are visible. Using a value that can be guessed, like an incremental id, can lead to security issues, since users can easily guess the URLs of other records.
|
|
194
|
+
|
|
195
|
+
A path authorises nothing. Which users may open a page is still set by [`auth.pages`](/protected-pages-apis) on its page id, and which records they may see is up to the requests that load them. Check in the request that the user may read the record the values name.
|
|
196
|
+
|
|
197
|
+
The browser is never sent the id or path of a page the user may not open, unless the page they are on already links to it.
|
|
198
|
+
|
|
199
|
+
## Build errors
|
|
200
|
+
|
|
201
|
+
The build fails when:
|
|
202
|
+
|
|
203
|
+
- a `path` is not a string (a path starting with a placeholder that is not quoted),
|
|
204
|
+
- a path has an empty segment, starts or ends with `/`, has a segment with characters a page id cannot use, or uses a placeholder name twice,
|
|
205
|
+
- a path has a placeholder inside a segment, an optional placeholder or a catch-all placeholder,
|
|
206
|
+
- two pages' paths tie,
|
|
207
|
+
- the `homePageId` page or an auth page has placeholders, or the `404` page has a `path`,
|
|
208
|
+
- an auth page has a `path`, and its `authPages` URL names its id instead,
|
|
209
|
+
- a `Link` action with a literal `pageId`, an HTML `data-page-id` link or a menu link does not give every placeholder of the page a value.
|