@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.
Files changed (284) hide show
  1. package/README.md +1 -0
  2. package/content/actions/downloadcsv.md +1 -1
  3. package/content/actions/emailotpsend.md +58 -0
  4. package/content/actions/emailotpverify.md +79 -0
  5. package/content/actions/getlocalstorage.md +43 -0
  6. package/content/actions/link.md +47 -1
  7. package/content/actions/login.md +25 -5
  8. package/content/actions/logout.md +7 -5
  9. package/content/actions/magiclinkverify.md +117 -0
  10. package/content/actions/pdfmake.md +2 -2
  11. package/content/actions/posthogalias.md +29 -0
  12. package/content/actions/posthogcapture.md +49 -0
  13. package/content/actions/posthogcapturepageleave.md +38 -0
  14. package/content/actions/posthogfeatureflag.md +50 -0
  15. package/content/actions/posthoggroup.md +37 -0
  16. package/content/actions/posthogidentify.md +54 -0
  17. package/content/actions/posthoginit.md +96 -0
  18. package/content/actions/posthogoptin.md +29 -0
  19. package/content/actions/posthogoptout.md +29 -0
  20. package/content/actions/posthogpageview.md +37 -0
  21. package/content/actions/posthogreloadfeatureflags.md +47 -0
  22. package/content/actions/posthogreset.md +28 -0
  23. package/content/actions/posthogsetpersonproperties.md +36 -0
  24. package/content/actions/removelocalstorage.md +28 -0
  25. package/content/actions/resetvalidation.md +7 -3
  26. package/content/actions/setdarkmode.md +3 -3
  27. package/content/actions/setglobal.md +2 -0
  28. package/content/actions/setlocale.md +1 -1
  29. package/content/actions/setlocalstorage.md +34 -0
  30. package/content/actions/validate.md +7 -4
  31. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  32. package/content/agents/agent-endpoint-tools.md +24 -0
  33. package/content/agents/agent-properties.md +13 -3
  34. package/content/agents/agent-server-hooks.md +1 -1
  35. package/content/agents/agentchat.md +43 -7
  36. package/content/agents/agentconversations.md +42 -8
  37. package/content/agents/agents-introduction.md +107 -0
  38. package/content/callback-reference/auth0logoutcallback.md +54 -0
  39. package/content/concepts/ai-agent-docs.md +455 -106
  40. package/content/concepts/blocks.md +150 -0
  41. package/content/concepts/connections-and-requests.md +402 -0
  42. package/content/concepts/custom-html.md +42 -0
  43. package/content/concepts/custom-styling.md +50 -5
  44. package/content/concepts/dynamic-page-content.md +309 -0
  45. package/content/concepts/events-and-actions.md +154 -2
  46. package/content/concepts/four-primitives.md +31 -0
  47. package/content/concepts/html-attributes.md +293 -0
  48. package/content/concepts/i18n.md +8 -3
  49. package/content/concepts/keyboard-shortcuts.md +2 -2
  50. package/content/concepts/layout-overview.md +1 -1
  51. package/content/concepts/logger.md +99 -0
  52. package/content/concepts/lowdefy-api.md +1319 -0
  53. package/content/concepts/lowdefy-schema.md +136 -3
  54. package/content/concepts/menus.md +8 -7
  55. package/content/concepts/module-authoring.md +76 -5
  56. package/content/concepts/modules.md +3 -1
  57. package/content/concepts/notifications.md +180 -0
  58. package/content/concepts/operators.md +7 -0
  59. package/content/concepts/page-and-app-state.md +252 -0
  60. package/content/concepts/page-paths.md +209 -0
  61. package/content/concepts/theming.md +582 -0
  62. package/content/connections/aigateway.md +375 -0
  63. package/content/connections/anthropic.md +169 -2
  64. package/content/connections/awss3.md +178 -2
  65. package/content/connections/axioshttp.md +181 -0
  66. package/content/connections/google.md +169 -2
  67. package/content/connections/mongodb.md +1014 -3
  68. package/content/connections/openai-connection.md +169 -2
  69. package/content/connections/sendgridmail.md +2 -0
  70. package/content/connections/smtp.md +3 -1
  71. package/content/connections/treg.md +329 -0
  72. package/content/container-blocks/affix.md +47 -7
  73. package/content/container-blocks/alert.md +76 -24
  74. package/content/container-blocks/badge.md +100 -24
  75. package/content/container-blocks/box.md +9 -9
  76. package/content/container-blocks/card.md +132 -27
  77. package/content/container-blocks/carousel.md +60 -7
  78. package/content/container-blocks/collapse.md +153 -9
  79. package/content/container-blocks/configprovider.md +35 -13
  80. package/content/container-blocks/confirmmodal.md +69 -23
  81. package/content/container-blocks/content.md +62 -98
  82. package/content/container-blocks/descriptions.md +45 -4
  83. package/content/container-blocks/drawer.md +139 -28
  84. package/content/container-blocks/dropdownmenu.md +119 -31
  85. package/content/container-blocks/flex.md +40 -62
  86. package/content/container-blocks/footer.md +15 -11
  87. package/content/container-blocks/googlemapsheatmap.md +1 -1
  88. package/content/container-blocks/googlemapsscript.md +2 -2
  89. package/content/container-blocks/header.md +71 -36
  90. package/content/container-blocks/label.md +34 -7
  91. package/content/container-blocks/layout.md +52 -34
  92. package/content/container-blocks/masonry.md +17 -71
  93. package/content/container-blocks/mobilemenu.md +131 -88
  94. package/content/container-blocks/modal.md +161 -26
  95. package/content/container-blocks/pageheadermenu.md +138 -31
  96. package/content/container-blocks/pagesidebarlayout.md +230 -27
  97. package/content/container-blocks/pagesidermenu.md +153 -43
  98. package/content/container-blocks/popover.md +34 -31
  99. package/content/container-blocks/result.md +32 -21
  100. package/content/container-blocks/sider.md +85 -122
  101. package/content/container-blocks/span.md +7 -7
  102. package/content/container-blocks/spinner.md +3 -3
  103. package/content/container-blocks/splitter.md +150 -68
  104. package/content/container-blocks/tabs.md +64 -12
  105. package/content/container-blocks/tooltip.md +22 -46
  106. package/content/container-blocks/watermark.md +22 -4
  107. package/content/controls/parallel_for.md +21 -2
  108. package/content/controls/reject.md +24 -3
  109. package/content/controls/return.md +17 -1
  110. package/content/controls/throw.md +1 -0
  111. package/content/controls/try.md +4 -2
  112. package/content/controls/while.md +46 -0
  113. package/content/deployment/deployment-environments.md +10 -7
  114. package/content/deployment/docker.md +22 -7
  115. package/content/deployment/node-server.md +4 -0
  116. package/content/deployment/vercel.md +17 -6
  117. package/content/display-blocks/aggrid.md +36 -19
  118. package/content/display-blocks/anchor.md +16 -15
  119. package/content/display-blocks/avatar.md +57 -37
  120. package/content/display-blocks/breadcrumb.md +70 -21
  121. package/content/display-blocks/button.md +93 -19
  122. package/content/display-blocks/calendar.md +12 -0
  123. package/content/display-blocks/clickablehtml.md +239 -0
  124. package/content/display-blocks/dangeroushtml.md +1 -1
  125. package/content/display-blocks/difflist.md +1 -1
  126. package/content/display-blocks/difftimeline.md +1 -1
  127. package/content/display-blocks/divider.md +64 -3
  128. package/content/display-blocks/dropdownbutton.md +81 -30
  129. package/content/display-blocks/echart.md +35 -1
  130. package/content/display-blocks/eventlog.md +363 -0
  131. package/content/display-blocks/floatbutton.md +129 -42
  132. package/content/display-blocks/html.md +61 -1
  133. package/content/display-blocks/icon.md +250 -67
  134. package/content/display-blocks/img.md +2 -2
  135. package/content/display-blocks/menu.md +146 -73
  136. package/content/display-blocks/message.md +38 -124
  137. package/content/display-blocks/notification.md +94 -222
  138. package/content/display-blocks/paragraph.md +59 -9
  139. package/content/display-blocks/pollingtimer.md +263 -0
  140. package/content/display-blocks/progress.md +96 -17
  141. package/content/display-blocks/qrcode.md +19 -4
  142. package/content/display-blocks/s3download.md +1 -1
  143. package/content/display-blocks/search.md +19 -9
  144. package/content/display-blocks/skeletonbutton.md +1 -0
  145. package/content/display-blocks/skeletoninput.md +1 -0
  146. package/content/display-blocks/statistic.md +75 -17
  147. package/content/display-blocks/steps.md +58 -25
  148. package/content/display-blocks/table.md +2527 -0
  149. package/content/display-blocks/tablelight.md +621 -0
  150. package/content/display-blocks/tag.md +102 -17
  151. package/content/display-blocks/title.md +50 -11
  152. package/content/display-blocks/tour.md +33 -23
  153. package/content/input-blocks/autocomplete.md +81 -9
  154. package/content/input-blocks/buttonselector.md +45 -8
  155. package/content/input-blocks/captcha.md +40 -0
  156. package/content/input-blocks/checkboxselector.md +97 -7
  157. package/content/input-blocks/checkboxswitch.md +33 -3
  158. package/content/input-blocks/colorselector.md +63 -14
  159. package/content/input-blocks/daterangeselector.md +165 -45
  160. package/content/input-blocks/dateselector.md +139 -41
  161. package/content/input-blocks/datetimeselector.md +158 -49
  162. package/content/input-blocks/inputgallery.md +3 -3
  163. package/content/input-blocks/intentinput.md +207 -0
  164. package/content/input-blocks/monthselector.md +120 -52
  165. package/content/input-blocks/multipleselector.md +150 -39
  166. package/content/input-blocks/numberinput.md +98 -12
  167. package/content/input-blocks/pagination.md +70 -14
  168. package/content/input-blocks/paragraphinput.md +51 -37
  169. package/content/input-blocks/passwordinput.md +60 -6
  170. package/content/input-blocks/phonenumberinput.md +59 -26
  171. package/content/input-blocks/placesautocomplete.md +319 -0
  172. package/content/input-blocks/radioselector.md +83 -7
  173. package/content/input-blocks/ratingslider.md +57 -26
  174. package/content/input-blocks/s3uploadbutton.md +24 -24
  175. package/content/input-blocks/s3uploaddragger.md +3 -3
  176. package/content/input-blocks/s3uploadphoto.md +5 -5
  177. package/content/input-blocks/segmentedselector.md +72 -32
  178. package/content/input-blocks/selector.md +109 -21
  179. package/content/input-blocks/switch.md +65 -17
  180. package/content/input-blocks/tableinput.md +445 -0
  181. package/content/input-blocks/tagmultipleselector.md +114 -0
  182. package/content/input-blocks/tagselector.md +114 -0
  183. package/content/input-blocks/textarea.md +32 -3
  184. package/content/input-blocks/textinput.md +70 -29
  185. package/content/input-blocks/tiptapinput.md +1 -1
  186. package/content/input-blocks/tiptapmentioninput.md +2 -2
  187. package/content/input-blocks/titleinput.md +39 -12
  188. package/content/input-blocks/treeinput.md +49 -25
  189. package/content/input-blocks/treemultipleselector.md +127 -10
  190. package/content/input-blocks/treeselector.md +97 -9
  191. package/content/input-blocks/upload.md +64 -15
  192. package/content/input-blocks/uploaddragger.md +17 -1
  193. package/content/input-blocks/uploadphoto.md +18 -1
  194. package/content/input-blocks/weekselector.md +120 -55
  195. package/content/learn/introduction.md +27 -0
  196. package/content/learn/quickstart.md +53 -0
  197. package/content/list-blocks/controlledlist.md +24 -15
  198. package/content/list-blocks/list.md +11 -11
  199. package/content/list-blocks/masonrylist.md +7 -34
  200. package/content/migration/auth-upgrade.md +337 -0
  201. package/content/migration/upgrade-guide.md +1 -0
  202. package/content/migration/v3-to-v4.md +417 -0
  203. package/content/migration/v6-to-v7.md +620 -0
  204. package/content/operators/_agent.md +155 -0
  205. package/content/operators/_app.md +2 -1
  206. package/content/operators/_array.md +122 -1
  207. package/content/operators/_build.md +1 -0
  208. package/content/operators/_credential.md +57 -0
  209. package/content/operators/_cron.md +292 -0
  210. package/content/operators/_date.md +2 -0
  211. package/content/operators/_error.md +24 -1
  212. package/content/operators/_get.md +6 -6
  213. package/content/operators/_hmac.md +78 -0
  214. package/content/operators/_js.md +2 -1
  215. package/content/operators/_location.md +1 -1
  216. package/content/operators/_media.md +13 -0
  217. package/content/operators/_module.md +56 -2
  218. package/content/operators/_operator.md +17 -3
  219. package/content/operators/_path_params.md +82 -0
  220. package/content/operators/_ref.md +258 -0
  221. package/content/operators/_request.md +1 -1
  222. package/content/operators/_request_details.md +6 -0
  223. package/content/operators/_type.md +14 -3
  224. package/content/operators/_url_query.md +2 -0
  225. package/content/operators/_user.md +3 -3
  226. package/content/plugins/plugins-actions.md +10 -0
  227. package/content/plugins/plugins-connections.md +25 -0
  228. package/content/plugins/plugins-dev.md +66 -0
  229. package/content/plugins/plugins-icon-sets.md +267 -0
  230. package/content/plugins/plugins-introduction.md +27 -1
  231. package/content/plugins/plugins.md +19 -0
  232. package/content/plugins/posthog.md +359 -0
  233. package/content/provider-reference/auth-js-providers.md +107 -0
  234. package/content/provider-reference/openidconnectprovider.md +44 -0
  235. package/content/recipes/recipes.md +16 -0
  236. package/content/reference/actions-reference.md +31 -0
  237. package/content/reference/blocks-reference.md +35 -0
  238. package/content/reference/cli.md +403 -0
  239. package/content/reference/connections-reference.md +23 -0
  240. package/content/reference/operators-reference.md +47 -0
  241. package/content/reference/reference.md +16 -0
  242. package/content/reference/schema-reference.md +12 -0
  243. package/content/testing/config-tests.md +677 -0
  244. package/content/testing/e2e-configuration.md +31 -1
  245. package/content/testing/e2e-getting-started.md +1 -1
  246. package/content/testing/e2e-introduction.md +1 -1
  247. package/content/testing/e2e-writing-tests.md +12 -1
  248. package/content/testing/explore-pull-request.md +136 -0
  249. package/content/testing/journey-data-sets.md +326 -0
  250. package/content/tutorial/tutorial-actions-operators.md +2 -2
  251. package/content/tutorial/tutorial-add-blocks.md +2 -2
  252. package/content/tutorial/tutorial-create-page.md +48 -2
  253. package/content/tutorial/tutorial-display-data-page.md +3 -3
  254. package/content/tutorial/tutorial-requests-api.md +155 -0
  255. package/content/tutorial/tutorial-requests-sql.md +153 -0
  256. package/content/tutorial/tutorial-start.md +66 -1
  257. package/content/user-authentication/auth-configuration.md +267 -0
  258. package/content/user-authentication/auth-providers.md +24 -0
  259. package/content/user-authentication/auth-steps.md +141 -0
  260. package/content/user-authentication/login-and-logout.md +160 -8
  261. package/content/user-authentication/mcp-oauth.md +424 -0
  262. package/content/user-authentication/organizations.md +246 -0
  263. package/content/user-authentication/protected-pages-apis.md +97 -0
  264. package/content/user-authentication/roles.md +49 -0
  265. package/content/user-authentication/two-factor.md +229 -0
  266. package/content/user-authentication/user-object.md +58 -0
  267. package/content/user-authentication/users-introduction.md +8 -0
  268. package/content/websockets/websocket-publish.md +105 -0
  269. package/content/websockets/websocket-subscriptions.md +136 -0
  270. package/content/websockets/websockets-introduction.md +101 -0
  271. package/hazards.json +44 -0
  272. package/index.json +3691 -14
  273. package/package.json +11 -1
  274. package/scripts/collectImportedFiles.js +80 -0
  275. package/scripts/extractAgentDocs.js +41 -30
  276. package/scripts/hashDocSources.js +38 -0
  277. package/scripts/isRedirectPage.js +26 -0
  278. package/scripts/recordSourceHashes.js +100 -0
  279. package/scripts/resolvePageSections.js +42 -0
  280. package/scripts/sectionKind.js +27 -0
  281. package/content/concepts/cli.md +0 -223
  282. package/content/other/introduction.md +0 -39
  283. package/content/other/next-auth-providers.md +0 -3
  284. /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.