@lowdefy/docs-content 6.1.0 → 7.0.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 (285) 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 +5 -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/setstate.md +2 -0
  31. package/content/actions/validate.md +7 -4
  32. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  33. package/content/agents/agent-endpoint-tools.md +24 -0
  34. package/content/agents/agent-properties.md +13 -3
  35. package/content/agents/agent-server-hooks.md +1 -1
  36. package/content/agents/agentchat.md +43 -7
  37. package/content/agents/agentconversations.md +42 -8
  38. package/content/agents/agents-introduction.md +107 -0
  39. package/content/callback-reference/auth0logoutcallback.md +54 -0
  40. package/content/concepts/ai-agent-docs.md +455 -106
  41. package/content/concepts/blocks.md +150 -0
  42. package/content/concepts/connections-and-requests.md +402 -0
  43. package/content/concepts/custom-html.md +42 -0
  44. package/content/concepts/custom-styling.md +50 -5
  45. package/content/concepts/dynamic-page-content.md +309 -0
  46. package/content/concepts/events-and-actions.md +154 -2
  47. package/content/concepts/four-primitives.md +31 -0
  48. package/content/concepts/html-attributes.md +293 -0
  49. package/content/concepts/i18n.md +8 -3
  50. package/content/concepts/keyboard-shortcuts.md +2 -2
  51. package/content/concepts/layout-overview.md +1 -1
  52. package/content/concepts/logger.md +99 -0
  53. package/content/concepts/lowdefy-api.md +1319 -0
  54. package/content/concepts/lowdefy-schema.md +136 -3
  55. package/content/concepts/menus.md +8 -7
  56. package/content/concepts/module-authoring.md +76 -5
  57. package/content/concepts/modules.md +3 -1
  58. package/content/concepts/notifications.md +180 -0
  59. package/content/concepts/operators.md +7 -0
  60. package/content/concepts/page-and-app-state.md +252 -0
  61. package/content/concepts/page-paths.md +209 -0
  62. package/content/concepts/theming.md +582 -0
  63. package/content/connections/aigateway.md +375 -0
  64. package/content/connections/anthropic.md +169 -2
  65. package/content/connections/awss3.md +178 -2
  66. package/content/connections/axioshttp.md +181 -0
  67. package/content/connections/google.md +169 -2
  68. package/content/connections/mongodb.md +1014 -3
  69. package/content/connections/openai-connection.md +169 -2
  70. package/content/connections/sendgridmail.md +2 -0
  71. package/content/connections/smtp.md +3 -1
  72. package/content/connections/treg.md +329 -0
  73. package/content/container-blocks/affix.md +47 -7
  74. package/content/container-blocks/alert.md +76 -24
  75. package/content/container-blocks/badge.md +100 -24
  76. package/content/container-blocks/box.md +9 -9
  77. package/content/container-blocks/card.md +132 -27
  78. package/content/container-blocks/carousel.md +60 -7
  79. package/content/container-blocks/collapse.md +153 -9
  80. package/content/container-blocks/configprovider.md +35 -13
  81. package/content/container-blocks/confirmmodal.md +69 -23
  82. package/content/container-blocks/content.md +62 -98
  83. package/content/container-blocks/descriptions.md +45 -4
  84. package/content/container-blocks/drawer.md +139 -28
  85. package/content/container-blocks/dropdownmenu.md +119 -31
  86. package/content/container-blocks/flex.md +40 -62
  87. package/content/container-blocks/footer.md +15 -11
  88. package/content/container-blocks/googlemapsheatmap.md +1 -1
  89. package/content/container-blocks/googlemapsscript.md +2 -2
  90. package/content/container-blocks/header.md +71 -36
  91. package/content/container-blocks/label.md +34 -7
  92. package/content/container-blocks/layout.md +52 -34
  93. package/content/container-blocks/masonry.md +17 -71
  94. package/content/container-blocks/mobilemenu.md +131 -88
  95. package/content/container-blocks/modal.md +161 -26
  96. package/content/container-blocks/pageheadermenu.md +138 -31
  97. package/content/container-blocks/pagesidebarlayout.md +230 -27
  98. package/content/container-blocks/pagesidermenu.md +153 -43
  99. package/content/container-blocks/popover.md +34 -31
  100. package/content/container-blocks/result.md +32 -21
  101. package/content/container-blocks/sider.md +85 -122
  102. package/content/container-blocks/span.md +7 -7
  103. package/content/container-blocks/spinner.md +3 -3
  104. package/content/container-blocks/splitter.md +150 -68
  105. package/content/container-blocks/tabs.md +64 -12
  106. package/content/container-blocks/tooltip.md +22 -46
  107. package/content/container-blocks/watermark.md +22 -4
  108. package/content/controls/parallel_for.md +21 -2
  109. package/content/controls/reject.md +24 -3
  110. package/content/controls/return.md +17 -1
  111. package/content/controls/throw.md +1 -0
  112. package/content/controls/try.md +4 -2
  113. package/content/controls/while.md +46 -0
  114. package/content/deployment/deployment-environments.md +10 -7
  115. package/content/deployment/docker.md +22 -7
  116. package/content/deployment/node-server.md +4 -0
  117. package/content/deployment/vercel.md +17 -6
  118. package/content/display-blocks/aggrid.md +33 -16
  119. package/content/display-blocks/anchor.md +16 -15
  120. package/content/display-blocks/avatar.md +57 -37
  121. package/content/display-blocks/breadcrumb.md +70 -21
  122. package/content/display-blocks/button.md +93 -19
  123. package/content/display-blocks/calendar.md +12 -0
  124. package/content/display-blocks/clickablehtml.md +239 -0
  125. package/content/display-blocks/dangeroushtml.md +1 -1
  126. package/content/display-blocks/difflist.md +1 -1
  127. package/content/display-blocks/difftimeline.md +1 -1
  128. package/content/display-blocks/divider.md +64 -3
  129. package/content/display-blocks/dropdownbutton.md +81 -30
  130. package/content/display-blocks/echart.md +35 -1
  131. package/content/display-blocks/eventlog.md +363 -0
  132. package/content/display-blocks/floatbutton.md +129 -42
  133. package/content/display-blocks/html.md +61 -1
  134. package/content/display-blocks/icon.md +250 -67
  135. package/content/display-blocks/img.md +2 -2
  136. package/content/display-blocks/menu.md +146 -73
  137. package/content/display-blocks/message.md +38 -124
  138. package/content/display-blocks/notification.md +94 -222
  139. package/content/display-blocks/paragraph.md +59 -9
  140. package/content/display-blocks/pollingtimer.md +263 -0
  141. package/content/display-blocks/progress.md +96 -17
  142. package/content/display-blocks/qrcode.md +19 -4
  143. package/content/display-blocks/s3download.md +1 -1
  144. package/content/display-blocks/search.md +19 -9
  145. package/content/display-blocks/skeletonbutton.md +1 -0
  146. package/content/display-blocks/skeletoninput.md +1 -0
  147. package/content/display-blocks/statistic.md +75 -17
  148. package/content/display-blocks/steps.md +58 -25
  149. package/content/display-blocks/table.md +2527 -0
  150. package/content/display-blocks/tablelight.md +621 -0
  151. package/content/display-blocks/tag.md +102 -17
  152. package/content/display-blocks/title.md +50 -11
  153. package/content/display-blocks/tour.md +33 -23
  154. package/content/input-blocks/autocomplete.md +81 -9
  155. package/content/input-blocks/buttonselector.md +45 -8
  156. package/content/input-blocks/captcha.md +40 -0
  157. package/content/input-blocks/checkboxselector.md +97 -7
  158. package/content/input-blocks/checkboxswitch.md +33 -3
  159. package/content/input-blocks/colorselector.md +63 -14
  160. package/content/input-blocks/daterangeselector.md +165 -45
  161. package/content/input-blocks/dateselector.md +139 -41
  162. package/content/input-blocks/datetimeselector.md +158 -49
  163. package/content/input-blocks/inputgallery.md +3 -3
  164. package/content/input-blocks/intentinput.md +207 -0
  165. package/content/input-blocks/monthselector.md +120 -52
  166. package/content/input-blocks/multipleselector.md +150 -39
  167. package/content/input-blocks/numberinput.md +98 -12
  168. package/content/input-blocks/pagination.md +70 -14
  169. package/content/input-blocks/paragraphinput.md +51 -37
  170. package/content/input-blocks/passwordinput.md +60 -6
  171. package/content/input-blocks/phonenumberinput.md +59 -26
  172. package/content/input-blocks/placesautocomplete.md +319 -0
  173. package/content/input-blocks/radioselector.md +83 -7
  174. package/content/input-blocks/ratingslider.md +57 -26
  175. package/content/input-blocks/s3uploadbutton.md +24 -24
  176. package/content/input-blocks/s3uploaddragger.md +3 -3
  177. package/content/input-blocks/s3uploadphoto.md +5 -5
  178. package/content/input-blocks/segmentedselector.md +72 -32
  179. package/content/input-blocks/selector.md +109 -21
  180. package/content/input-blocks/switch.md +65 -17
  181. package/content/input-blocks/tableinput.md +445 -0
  182. package/content/input-blocks/tagmultipleselector.md +114 -0
  183. package/content/input-blocks/tagselector.md +114 -0
  184. package/content/input-blocks/textarea.md +32 -3
  185. package/content/input-blocks/textinput.md +70 -29
  186. package/content/input-blocks/tiptapinput.md +1 -1
  187. package/content/input-blocks/tiptapmentioninput.md +2 -2
  188. package/content/input-blocks/titleinput.md +39 -12
  189. package/content/input-blocks/treeinput.md +49 -25
  190. package/content/input-blocks/treemultipleselector.md +127 -10
  191. package/content/input-blocks/treeselector.md +97 -9
  192. package/content/input-blocks/upload.md +64 -15
  193. package/content/input-blocks/uploaddragger.md +17 -1
  194. package/content/input-blocks/uploadphoto.md +18 -1
  195. package/content/input-blocks/weekselector.md +120 -55
  196. package/content/learn/introduction.md +27 -0
  197. package/content/learn/quickstart.md +53 -0
  198. package/content/learn/showcase.md +8 -0
  199. package/content/list-blocks/controlledlist.md +24 -15
  200. package/content/list-blocks/list.md +11 -11
  201. package/content/list-blocks/masonrylist.md +7 -34
  202. package/content/migration/auth-upgrade.md +337 -0
  203. package/content/migration/upgrade-guide.md +1 -0
  204. package/content/migration/v3-to-v4.md +417 -0
  205. package/content/migration/v6-to-v7.md +620 -0
  206. package/content/operators/_agent.md +155 -0
  207. package/content/operators/_app.md +2 -1
  208. package/content/operators/_array.md +122 -1
  209. package/content/operators/_build.md +1 -0
  210. package/content/operators/_credential.md +57 -0
  211. package/content/operators/_cron.md +292 -0
  212. package/content/operators/_date.md +2 -0
  213. package/content/operators/_error.md +24 -1
  214. package/content/operators/_get.md +6 -6
  215. package/content/operators/_hmac.md +78 -0
  216. package/content/operators/_js.md +2 -1
  217. package/content/operators/_location.md +1 -1
  218. package/content/operators/_media.md +13 -0
  219. package/content/operators/_module.md +56 -2
  220. package/content/operators/_operator.md +17 -3
  221. package/content/operators/_path_params.md +82 -0
  222. package/content/operators/_ref.md +258 -0
  223. package/content/operators/_request.md +1 -1
  224. package/content/operators/_request_details.md +6 -0
  225. package/content/operators/_type.md +14 -3
  226. package/content/operators/_url_query.md +2 -0
  227. package/content/operators/_user.md +3 -3
  228. package/content/plugins/plugins-actions.md +10 -0
  229. package/content/plugins/plugins-connections.md +25 -0
  230. package/content/plugins/plugins-dev.md +66 -0
  231. package/content/plugins/plugins-icon-sets.md +267 -0
  232. package/content/plugins/plugins-introduction.md +27 -1
  233. package/content/plugins/plugins.md +19 -0
  234. package/content/plugins/posthog.md +359 -0
  235. package/content/provider-reference/auth-js-providers.md +107 -0
  236. package/content/provider-reference/openidconnectprovider.md +44 -0
  237. package/content/recipes/recipes.md +16 -0
  238. package/content/reference/actions-reference.md +31 -0
  239. package/content/reference/blocks-reference.md +35 -0
  240. package/content/reference/cli.md +403 -0
  241. package/content/reference/connections-reference.md +23 -0
  242. package/content/reference/operators-reference.md +47 -0
  243. package/content/reference/reference.md +16 -0
  244. package/content/reference/schema-reference.md +12 -0
  245. package/content/testing/config-tests.md +677 -0
  246. package/content/testing/e2e-configuration.md +31 -1
  247. package/content/testing/e2e-getting-started.md +1 -1
  248. package/content/testing/e2e-introduction.md +1 -1
  249. package/content/testing/e2e-writing-tests.md +12 -1
  250. package/content/testing/explore-pull-request.md +136 -0
  251. package/content/testing/journey-data-sets.md +326 -0
  252. package/content/tutorial/tutorial-actions-operators.md +2 -2
  253. package/content/tutorial/tutorial-add-blocks.md +2 -2
  254. package/content/tutorial/tutorial-create-page.md +48 -2
  255. package/content/tutorial/tutorial-display-data-page.md +3 -3
  256. package/content/tutorial/tutorial-requests-api.md +155 -0
  257. package/content/tutorial/tutorial-requests-sql.md +153 -0
  258. package/content/tutorial/tutorial-start.md +66 -1
  259. package/content/user-authentication/auth-configuration.md +267 -0
  260. package/content/user-authentication/auth-providers.md +24 -0
  261. package/content/user-authentication/auth-steps.md +141 -0
  262. package/content/user-authentication/login-and-logout.md +160 -8
  263. package/content/user-authentication/mcp-oauth.md +424 -0
  264. package/content/user-authentication/organizations.md +246 -0
  265. package/content/user-authentication/protected-pages-apis.md +97 -0
  266. package/content/user-authentication/roles.md +49 -0
  267. package/content/user-authentication/two-factor.md +229 -0
  268. package/content/user-authentication/user-object.md +58 -0
  269. package/content/user-authentication/users-introduction.md +8 -0
  270. package/content/websockets/websocket-publish.md +105 -0
  271. package/content/websockets/websocket-subscriptions.md +136 -0
  272. package/content/websockets/websockets-introduction.md +101 -0
  273. package/hazards.json +56 -0
  274. package/index.json +3458 -14
  275. package/package.json +10 -1
  276. package/scripts/extractAgentDocs.js +41 -30
  277. package/scripts/hashDocSources.js +38 -0
  278. package/scripts/isRedirectPage.js +26 -0
  279. package/scripts/recordSourceHashes.js +97 -0
  280. package/scripts/resolvePageSections.js +42 -0
  281. package/scripts/sectionKind.js +27 -0
  282. package/content/concepts/cli.md +0 -223
  283. package/content/other/introduction.md +0 -39
  284. package/content/other/next-auth-providers.md +0 -3
  285. /package/content/{other → actions}/updatesession.md +0 -0
@@ -0,0 +1,150 @@
1
+ # Blocks
2
+
3
+ A Lowdefy page is compiled out of an arrangement of blocks. Every HTML element of this page is rendered as a result of a block placed and configured on the page. A Lowdefy Block is just a React component. A large number of default blocks make it easy to build apps with Lowdefy, and for more specific requirements, custom blocks can be added to apps as [plugins](/plugins).
4
+
5
+ Blocks make it simple for Lowdefy developers to create apps since they only have to decide which block type to use, where in the layout the block should render, and what the block should do by defining the block's `properties` and `events`. How a block implements these `properties` and `events` is up to the specific block type.
6
+
7
+ All Lowdefy blocks are categorized according to their primary function:
8
+ - `display` - Display page elements.
9
+ - `input` - Modify a value in [`state`](/page-and-app-state).
10
+ - `container` - Render other blocks into [`content slots`](/layout).
11
+ - `list` - Render `content slots` and blocks for each element in the data array represented in [`state`](/page-and-app-state).
12
+
13
+ When `state` updates or a requests call completes, the Lowdefy engine re-evaluates all operators and re-renders blocks for which the operator evaluation is different from the previous render result. The result is _live updates_ to all blocks on a page. Operators can be used to build _live update_ logic into all block fields, except for the `id`, `type`, `slots` and `blocks` fields.
14
+
15
+ The schema for a Lowdefy block is:
16
+
17
+ - `id: string`: An identifier for a block. For `Input` blocks the block `id` sets the field key which the block will modify in `state`. Field _dot-notation_ can be used to express fields which are nested in objects or arrays.
18
+ - `type: string`: __Required__ - This is the block type identifier and defines what block to use. The block type used must either be a default block type or can defined in the app's [`plugins`](/plugins) configuration.
19
+ - `properties: object`: All the settings passed to a block component. __Operators are evaluated__.
20
+ - `blocks: array`: An array of blocks to render to the default `content` slot for `container` and `list` blocks. See [layout](/layout-overview) for more details on how to use the `blocks` array.
21
+ - `slots: object`: Used to set the content slots and content layout settings for `container` and `list` blocks. See [layout](/layout-overview) for more details on how to use `slots`.
22
+ - `events: object`: Used to define [`actions`](/events-and-actions) that run when the block triggers an [`event`](/events-and-actions).
23
+ - `layout: object`: Used to define the [layout](/layout-overview) settings for a block. __Operators are evaluated__.
24
+ - `skeleton: object`: Used to overwrite a block's default loading behavior by rendering a skeleton. Any block types from [`@lowdefy/blocks-basic`](https://github.com/lowdefy/lowdefy/tree/main/packages/plugins/blocks/blocks-basic/src/blocks) and [`@lowdefy/blocks-loaders`](https://github.com/lowdefy/lowdefy/tree/main/packages/plugins/blocks/blocks-loaders/src/blocks) can be used in the skeleton definition, including sub-blocks. __Operators are evaluated__.
25
+ - `loading: boolean`: When true, renders the block in loading. If a `skeleton` is defined, it will be rendered, else the block's default loading behavior will be rendered. __Operators are evaluated__.
26
+ - `required: boolean | string`: For `input` blocks, whether or not a value is required in `state` when the [`Validate`](/Validate) action is called. Can be either a boolean or a string that is used as the validation error message . __Operators are evaluated__.
27
+ - `class: string | array | object`: CSS class names to apply to the block. Supports Tailwind CSS utility classes. __Operators are evaluated__.
28
+ - `style: css object`: Inline CSS styles. Flat CSS targets the layout wrapper. Use `.`-prefixed keys (e.g. `.element`, `.header`, `.body`) to target specific block parts. __Operators are evaluated__.
29
+ - `validate: array`: A list of validation tests to pass when the [`Validate`](/Validate) action is called. __Operators are evaluated__.
30
+ - `visible: boolean`: Controls whether or not to render a block. Operators are generally used here, and must evaluate to `false` to make the block invisible. Blocks with `visible: false` are excluded from `state`. __Operators are evaluated__.
31
+
32
+ ## Block types
33
+
34
+ Lowdefy has a set of default block types as defined in the Lowdefy docs. Most of the default Lowdefy blocks aim to cover a very generic implementation of the [Ant Design](https://ant.design/components/overview) React component library, but some addition component libraries are also included. To use all the default block types, you can simply use the block `type` key, such as [`Button`](/Button), [`TextInput`](/TextInput), or [`Box`](/Box).
35
+
36
+ ###### Default block type config example:
37
+ ```yaml
38
+ lowdefy: 6.1.0
39
+ pages:
40
+ - id: example_dashboard
41
+ type: PageHeaderMenu
42
+ blocks:
43
+ - id: basic_chart
44
+ type: EChart
45
+ properties:
46
+ # ... EChart properties
47
+ ```
48
+
49
+ However, the default types can be overwritten or additional types can be defined as required. This is done by defining additional [`plugins`](/plugins).
50
+
51
+ ## Input block validation
52
+
53
+ All `input` block types maintain a value in the page [`state`](/page-and-app-state). This value is set to the field name matching the block `id`. Nested fields can be created by using _dot notation_ in the `id` to specify the field path, for example, `id: "a.b.c"` will produce a value `{"a": {"b": {"c": null }}}` in the page `state`.
54
+
55
+ Client side field validation can be applied by setting the `required` and / or `validate` block fields. Field validation is first evaluated when the [`Validate`](/Validate) action is invoked on a page.
56
+
57
+ ##### required schema:
58
+
59
+ `required` can be a `boolean` or `string` type. When `required: true` the field label will indicate this with a red asterisk for user feedback, and a value will have to be supplied to the field in order to pass validation. If `required` is set to a `string`, this string will be used as the feedback message when the validation fails.
60
+
61
+ ```yaml
62
+ - id: name
63
+ type: TextInput
64
+ required: Please provide your name.
65
+ properties:
66
+ title: Name
67
+ ```
68
+
69
+ ##### validate schema:
70
+
71
+ The `validate` field takes an `array` of test `objects` to evaluate before passing the field validation. This list of tests are evaluated sequentially, so the first test that fails will be used as the feedback message to the user.
72
+
73
+ The schema for the validation test `objects`:
74
+ - `pass: boolean`: __Required__ - The test that validates if this item passes or not. This is usually written with operators which evaluate to `true` or `false`. __Operators are evaluated__.
75
+ - `message: string`: __Required__ - The feedback message to the user if this validation tests fails. __Operators are evaluated__.
76
+ - `status: enum`: The feedback type to present to the user. Option are `error` and `warning`. Default is `error`. __Operators are evaluated__.
77
+
78
+ The following `validate` example first verifies that something was entered into the `email` field, then checks that the field passes a email regex validation using the [`_regex`](/_regex) operator:
79
+
80
+ ```yaml
81
+ - id: email
82
+ type: TextInput
83
+ validate:
84
+ - message: Please enter a email address.
85
+ status: error
86
+ pass:
87
+ _ne:
88
+ - _state: email
89
+ - null
90
+ - message: Please provide a valid email address.
91
+ status: error
92
+ pass:
93
+ _regex: '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$'
94
+ properties:
95
+ title: Email
96
+ ```
97
+
98
+ ## Block events
99
+
100
+ By default all blocks implement `onMount` and `onMountAsync` events. Both the `onMount` and `onMountAsync` events are triggered when the block is mounted. For the `onMount` event, the block only mounts when the event action chain is completed, however, for the `onMountAsync` event, the block will mount as soon as possible while the event actions complete execution.
101
+
102
+ Apart from the `onMount` and `onMountAsync` events, most blocks also implement their own block specific events such as `onOpen` for [Modal](/Modal) or `onClick` for [Button](/Button). See the events tab on each block's documentation for more details.
103
+
104
+ See [the events and actions page](/events-and-actions) for more details.
105
+
106
+ ## Block loading
107
+
108
+ Blocks will only start rendering when the `onInit` event has completed its actions. The `onMount` event on blocks will render blocks with loading active. By default, some blocks will change behavior while they are loading. For example, input blocks will be disabled during loading. The loading behavior of blocks can be controlled using the `loading` block property. Setting `loading` to `true` on a container or list block, will result in rendering all child blocks with loading active.
109
+
110
+ Often it is useful to render a skeleton of blocks instead of the blocks' default loading behavior. When block definitions are provided to the `skeleton` property on a block, this `skeleton` definition will be rendered when loading is active. Any block types from [`@lowdefy/blocks-basic`](https://github.com/lowdefy/lowdefy/tree/main/packages/plugins/blocks/blocks-basic/src/blocks) and [`@lowdefy/blocks-loaders`](https://github.com/lowdefy/lowdefy/tree/main/packages/plugins/blocks/blocks-loaders/src/blocks) can be used as the skeleton definition. Skeleton blocks are not real blocks, they do not have values in state or events, but they can contain other skeleton blocks as children.
111
+
112
+ ##### Block `loading` and `skeleton` example:
113
+
114
+ ```yaml
115
+ pages:
116
+ - id: page_one
117
+ type: Box
118
+ blocks:
119
+ # ...
120
+ - id: paragraph_one
121
+ type: Paragraph
122
+ loading:
123
+ _eq:
124
+ - _state: done
125
+ - false
126
+ skeleton:
127
+ type: SkeletonParagraph
128
+ properties:
129
+ lines: 1
130
+ properties:
131
+ content: Lorem ipsum dolor sit amet.
132
+ # ...
133
+ ```
134
+
135
+ ## TLDR
136
+ - All user interfaces in Lowdefy are assembled out of blocks, which are React components.
137
+ #### Block types
138
+ - There are four block categories: `display`, `input`, `container` and `list`.
139
+ - Operators re-evaluate on every [`state`](/page-and-app-state) update or when request calls complete. This allows blocks to _live update_.
140
+ - Lowdefy has built in default block types, however this can be overwritten or extended with custom blocks by defining [`plugins`](/plugins) on the Lowdefy config root.
141
+ - `input` blocks maintain a value in `state` matching the block `id` key. _Dot notation_ applies to specify nested fields.
142
+ #### Block validation
143
+ - Field level input validation can be achieved by marking an `input` block as `required` or by specifying a list of `validate` tests.
144
+ - Validation is invoked using the [`Validate`](/Validate) action.
145
+ #### Block events
146
+ - All blocks have`onMount` and `onMountAsync` events.
147
+ - Each block implements it's own additional events such as `onClick` etc.
148
+ #### Block loading
149
+ - Some blocks gracefully handle a loading state while `onMount` events are being executed.
150
+ - A block's default loading can be overwritten by defining custom `skeleton` settings on a block.
@@ -4,4 +4,406 @@ In a Lowdefy app you can integrate with other services like API's or databases u
4
4
 
5
5
  > Sensitive information like passwords or API keys are often required to use external services. The <a href = "./_secret">_secret</a> operator should be used to reference these secrets, they should never be coded directly in your app, or committed to source control.
6
6
 
7
+ To implement requests, the following steps are required:
8
+ - Define a connection.
9
+ - Define a request.
10
+ - Call the request using a [Request](/Request) action.
11
+ - Use returned data by making use of the [_request](/_request) operator.
12
+
13
+ ## Connections
14
+
15
+ Connections are defined at the root of your Lowdefy configuration, in the `connections` array. Each connection must have an `id`, a `type`, and `properties` defining the connection. Operators in connection properties are evaluated every time a request is called.
16
+
17
+ The schema for a Lowdefy connection is:
18
+
19
+ - `id: string`: __Required__ - A unique identifier for the connection. This is used by requests to specify which connection to use.
20
+ - `type: string`: __Required__ - The connection type to be used.
21
+ - `properties: object`: The settings passed to the connection. __Operators are evaluated__.
22
+
23
+ ###### Connections definition example:
24
+ ```yaml
25
+ lowdefy: 6.1.0
26
+ connections:
27
+ - id: connection1
28
+ type: ConnectionType1
29
+ properties:
30
+ # ...
31
+ - id: connection2
32
+ type: ConnectionType2
33
+ properties:
34
+ # ...
35
+ pages:
36
+ # ...
37
+ ```
38
+
39
+ Our goal is to make connections for everything. As the Lowdefy community grows, we will continue to develop the most requested connections. If the connection you require is not supported yet, please head over to our [new connections voting board](https://github.com/lowdefy/lowdefy/discussions/309) to request and vote for new connections.
40
+
41
+ ## Requests
42
+
43
+ Requests can be defined on any block, and the results of the request can be access using the `_request` operator anywhere on the same page. Requests must have an `id`, `type`, `connectionId` field specifying the connection to use, and `properties` defining the request settings. Requests can be called using the [`Request`](/Request) action.
44
+
45
+ Data that should be passed to the request from the client can be defined in the `payload` field. Operators can be used to create the payload. An example of this would be to use the `_state` operator to include the value of an input block in the payload. The data in the payload can be accessed in the request by making use of the [`_payload`](/_payload) operator in the `properties` field. The operators defined in the properties field are evaluated on the server, while those defined in the payload field are evaluated on the client. Operators in the request are evaluated every time a request is called.
46
+
7
47
  > The <code>_user</code> operator should be used under <code>properties</code> and not <code>payload</code>. This is important since operators under <code>payload</code> are evaluated on the client, and are therefore vulnerable to users with malicious intent.
48
+
49
+ The schema for a Lowdefy request is:
50
+
51
+ - `id: string`: __Required__ - A identifier for the request. It must be unique within the page the request is defined in.
52
+ - `type: string`: __Required__ - The request type to be used. It must be a type supported by the connection type.
53
+ - `payload: object`: The operators to be used inside of the request. __Operators are evaluated on the client__.
54
+ - `connectionId: string`: __Required__ - The `id` of the connection that should be used.
55
+ - `properties: object`: The settings passed to the request. Make use of [`_payload`](/_payload) operator to use operators that were evaluated in `payload` mentioned above. __Operators are evaluated on the server__.
56
+
57
+ ###### Requests definition example:
58
+ ```yaml
59
+ id: block_with_requests
60
+ type: BlockType
61
+ requests:
62
+ - id: request1
63
+ type: RequestType1
64
+ connectionId: connectionId1 # Connection with id: connectionId1 must be defined
65
+ payload:
66
+ field:
67
+ _state: field
68
+ properties:
69
+ # ...
70
+ - id: request2
71
+ type: RequestType2
72
+ connectionId: connectionId2 # Connection with id: connectionId2 must be defined
73
+ properties:
74
+ # ...
75
+ properties:
76
+ # ...
77
+ ```
78
+
79
+ ## Request Action
80
+
81
+ The `Request` action calls a request, or if used during an `onInit` event, calls those requests while a page loads. Read more about the `Request` action [here](/Request).
82
+
83
+ ###### Call a single request:
84
+ ```yaml
85
+ - id: call_one_request
86
+ type: Request
87
+ params: request1
88
+ ```
89
+
90
+ ## _request operator
91
+
92
+ The `_request` operator returns the response value of a request. If the request has not yet been called, or is still executing, the returned value is `null`. Read more about the `_request` operator [here](/_request). For more detailed information about a request, the [_request_details](/_request_details) operator can be used.
93
+
94
+ ###### Using a request response:
95
+ ```yaml
96
+ _request: my_request
97
+ ```
98
+
99
+ ## General Example
100
+
101
+ ###### lowdefy.yaml
102
+ ```yaml
103
+ lowdefy: 6.1.0
104
+
105
+ connections:
106
+ - id: connection1
107
+ type: ConnectionType1
108
+ properties:
109
+ # ...
110
+
111
+ pages:
112
+ - id: page1
113
+ type: PageHeaderMenu
114
+ properties:
115
+ title: Page 1
116
+ requests:
117
+ - id: request1
118
+ type: RequestType1
119
+ connectionId: connection1
120
+ properties:
121
+ # ...
122
+ events:
123
+ onInit:
124
+ - id: call_request
125
+ type: Request
126
+ params: request1
127
+ blocks:
128
+ - id: content_card
129
+ type: Card
130
+ blocks:
131
+ - id: paragraph
132
+ type: Paragraph
133
+ properties:
134
+ content:
135
+ _request: request1
136
+ ```
137
+
138
+ ## Working Example
139
+
140
+ For this example, a connection to [{JSON}Placeholder](https://jsonplaceholder.typicode.com/) will be used.
141
+ To create this `connection`, define the connection as follows in the `lowdefy.yaml` file:
142
+
143
+ ###### lowdefy.yaml
144
+ ```yaml
145
+ lowdefy: 6.1.0
146
+
147
+ connections:
148
+ - id: my_api
149
+ type: AxiosHttp
150
+ properties:
151
+ baseURL: https://jsonplaceholder.typicode.com
152
+
153
+ pages:
154
+ - id: home
155
+ type: PageHeaderMenu
156
+ ```
157
+
158
+ To use this connection, a `request` must be defined, which references the corresponding `connectionId`. A request to get the list of users can be added to the home page as follows:
159
+
160
+ ###### lowdefy.yaml
161
+ ```yaml
162
+ lowdefy: 6.1.0
163
+
164
+ connections:
165
+ - id: my_api
166
+ type: AxiosHttp
167
+ properties:
168
+ baseURL: https://jsonplaceholder.typicode.com
169
+
170
+ pages:
171
+ - id: home
172
+ type: PageHeaderMenu
173
+
174
+ requests:
175
+ - id: get_users
176
+ type: AxiosHttp
177
+ connectionId: my_api
178
+ properties:
179
+ url: /users
180
+ ```
181
+
182
+ This request should be called when the page is mounted. To do this, the [`Request`](/Request) action will be used during the `onMount` event of the home page[`PageHeaderMenu`](/PageHeaderMenu) block.
183
+
184
+ ###### lowdefy.yaml
185
+ ```yaml
186
+ lowdefy: 6.1.0
187
+
188
+ connections:
189
+ - id: my_api
190
+ type: AxiosHttp
191
+ properties:
192
+ baseURL: https://jsonplaceholder.typicode.com
193
+
194
+ pages:
195
+ - id: home
196
+ type: PageHeaderMenu
197
+
198
+ requests:
199
+ - id: get_users
200
+ type: AxiosHttp
201
+ connectionId: my_api
202
+ properties:
203
+ url: /users
204
+
205
+ events:
206
+ onMount:
207
+ - id: fetch_get_users
208
+ type: Request
209
+ params: get_users
210
+ ```
211
+
212
+ A block can be added to the page, that can use or display the data returned by this request. The [`_request`](/_request) operator is used to get the the results of the request.
213
+ In this example, a [`Selector`](/Selector) block will be added. The [`_array.map`](/_array) operator is used to get the data in a form that can be used by the Selector.
214
+
215
+ ###### lowdefy.yaml
216
+ ```yaml
217
+ lowdefy: 6.1.0
218
+
219
+ connections:
220
+ - id: my_api
221
+ type: AxiosHttp
222
+ properties:
223
+ baseURL: https://jsonplaceholder.typicode.com
224
+
225
+ pages:
226
+ - id: home
227
+ type: PageHeaderMenu
228
+
229
+ requests:
230
+ - id: get_users
231
+ type: AxiosHttp
232
+ connectionId: my_api
233
+ properties:
234
+ url: /users
235
+
236
+ events:
237
+ onMount:
238
+ - id: fetch_get_users
239
+ type: Request
240
+ params: get_users
241
+
242
+ blocks:
243
+ - id: user_id
244
+ type: Selector
245
+ properties:
246
+ title: Select a User
247
+ options:
248
+ _array.map:
249
+ - _request: get_users.data
250
+ - _function:
251
+ label:
252
+ __args: 0.name
253
+ value:
254
+ __args: 0.id
255
+ ```
256
+
257
+ To get the posts made by the selected user, a new request should be created and called once the value of the Selector changes.
258
+ To do this, create a new request that will make use of a `payload` to get the posts with the selected user id. Add an `onChange` event on the `Selector` block, during which the new request is called.
259
+
260
+ ###### lowdefy.yaml
261
+ ```yaml
262
+ lowdefy: 6.1.0
263
+
264
+ connections:
265
+ - id: my_api
266
+ type: AxiosHttp
267
+ properties:
268
+ baseURL: https://jsonplaceholder.typicode.com
269
+
270
+ pages:
271
+ - id: home
272
+ type: PageHeaderMenu
273
+
274
+ requests:
275
+ - id: get_users
276
+ type: AxiosHttp
277
+ connectionId: my_api
278
+ properties:
279
+ url: /users
280
+ - id: get_posts
281
+ type: AxiosHttp
282
+ connectionId: my_api
283
+ payload:
284
+ id:
285
+ _state: user_id
286
+ properties:
287
+ url:
288
+ _string.concat:
289
+ - /users/
290
+ - _payload: id
291
+ - /posts
292
+
293
+ events:
294
+ onMount:
295
+ - id: fetch_get_users
296
+ type: Request
297
+ params: get_users
298
+
299
+ blocks:
300
+ - id: user_id
301
+ type: Selector
302
+ properties:
303
+ title: Select a User
304
+ options:
305
+ _array.map:
306
+ - _request: get_users.data
307
+ - _function:
308
+ label:
309
+ __args: 0.name
310
+ value:
311
+ __args: 0.id
312
+ events:
313
+ onChange:
314
+ - id: fetch_get_posts
315
+ type: Request
316
+ params: get_posts
317
+ ```
318
+
319
+ Set the data from the result of this request in state by using the [`SetState`](/SetState) action. To display the posts, make use of a [`List`](/List) block. In this `List` block, display the data returned of each post in a [`Markdown`](/Markdown) block.
320
+ This is done as follows:
321
+
322
+ ###### lowdefy.yaml
323
+ ```yaml
324
+ lowdefy: 6.1.0
325
+
326
+ connections:
327
+ - id: my_api
328
+ type: AxiosHttp
329
+ properties:
330
+ baseURL: https://jsonplaceholder.typicode.com
331
+
332
+ pages:
333
+ - id: home
334
+ type: PageHeaderMenu
335
+
336
+ requests:
337
+ - id: get_users
338
+ type: AxiosHttp
339
+ connectionId: my_api
340
+ properties:
341
+ url: /users
342
+
343
+ - id: get_posts
344
+ type: AxiosHttp
345
+ connectionId: my_api
346
+ payload:
347
+ id:
348
+ _state: user_id
349
+ properties:
350
+ url:
351
+ _string.concat:
352
+ - /users/
353
+ - _payload: id
354
+ - /posts
355
+
356
+ events:
357
+ onMount:
358
+ - id: fetch_get_users
359
+ type: Request
360
+ params: get_users
361
+
362
+ blocks:
363
+ - id: user_id
364
+ type: Selector
365
+ properties:
366
+ title: Select a User
367
+ options:
368
+ _array.map:
369
+ - _request: get_users.data
370
+ - _function:
371
+ label:
372
+ __args: 0.name
373
+ value:
374
+ __args: 0.id
375
+ events:
376
+ onChange:
377
+ - id: fetch_get_posts
378
+ type: Request
379
+ params: get_posts
380
+ - id: set_posts
381
+ type: SetState
382
+ params:
383
+ posts:
384
+ _request: get_posts.data
385
+
386
+ - id: posts
387
+ type: List
388
+ blocks:
389
+ - id: posts.$
390
+ type: Markdown
391
+ style:
392
+ padding: 10
393
+ properties:
394
+ content:
395
+ _string.concat:
396
+ - |
397
+ ```yaml
398
+ - _custom_yaml_stringify:
399
+ - _state: posts.$
400
+ - |
401
+ ```
402
+
403
+ ```
404
+
405
+ ### TLDR
406
+ - `connections` define links to other services, like connecting to a database. They are defined at the root of the lowdefy configuration.
407
+ - `requests` use connections to make a call to the connected external services.
408
+ - Use the `payload` object on a request to pass data such as state values from the app client to the server as required.
409
+ - Use the [`_secret`](/_secret) operator to reference API keys or other secrets as required - do not code secrets into your config or commit secrets to your config source control.
@@ -1,3 +1,45 @@
1
1
  # Custom HTML
2
2
 
3
3
  > SECURITY WARNING: Custom HTML can execute JavaScript inside your Lowdefy app. Insecure code can expose your app or data. Since Lowdefy doesn't validate your custom code, make sure that you only load trusted code.
4
+
5
+ It is possible to extend the functionality of a Lowdefy app by loading custom code (HTML, CSS and JavaScript) into the HTML `head` and `body` of all pages. This can be useful for executing third party code such as Google Analytics, Intercom, etc. However, if the goal is to extend the functionality of your Lowdefy app with custom blocks, operators, actions or requests, use [plugins](/plugins).
6
+
7
+ The content loaded into the `head` and `body` tag can be any valid HTML. Be sure to only load trusted code into your app, as this code will be able to execute JavaScript on all pages of your Lowdefy app, which could expose you app or data to security vulnerabilities. Your own code can also be hosted from the [Lowdefy public folder](/hosting-files).
8
+
9
+ ## Schema to load custom code
10
+
11
+ - `app.html.appendHead: string`: Any valid HTML content can be loaded just before the `</head>` tag of the page.
12
+ - `app.html.appendBody: string`: Any valid HTML content can be loaded just before the `</body>` tag of the page.
13
+
14
+ Most often it is convenient to abstract this HTML out to a separate file using the [`_ref`](/_ref) operator.
15
+
16
+ When the app sends a [Content Security Policy](/lowdefy-schema#security), every `<script>` and `<style>` element in `appendHead` and `appendBody` gets the page's nonce, so they keep running. Scripts and styles they load from other hosts need those hosts added to the policy.
17
+
18
+ > __Warning__: Code imported using `appendHead` or `appendBody` will be loaded, and can execute JavaScript on every page of your Lowdefy app.
19
+
20
+ #### Examples
21
+
22
+ ###### Loading third party code snippet like Google Analytics:
23
+
24
+ To add [Google Analytics](/https://developers.google.com/analytics/devguides/collection/analyticsjs) to a Lowdefy app, the `lowdefy.yaml` can be setup with:
25
+
26
+ ```yaml
27
+ name: google-analytics-example
28
+ lowdefy: 6.1.0
29
+ # ...
30
+ app:
31
+ html:
32
+ appendHead: |
33
+ <!-- Google Analytics -->
34
+ <script>
35
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
36
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
37
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
38
+ })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
39
+
40
+ ga('create', 'UA-XXXXX-Y', 'auto');
41
+ ga('send', 'pageview');
42
+ </script>
43
+ <!-- End Google Analytics -->
44
+ # ...
45
+ ```