-
-
Notifications
You must be signed in to change notification settings - Fork 155
/
lowdefy-schema.yaml
316 lines (262 loc) · 15.4 KB
/
lowdefy-schema.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
# Copyright 2020-2022 Lowdefy, Inc
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
_ref:
path: templates/general.yaml.njk
vars:
pageId: lowdefy-schema
pageTitle: Lowdefy App Schema
section: Concepts
filePath: concepts/lowdefy-schema.yaml
content:
- id: md1
type: MarkdownWithCode
properties:
content: |
A Lowdefy app is written as YAML files, which are combined together using the `_ref` operator when the app is built, into a configuration object that describes the entire app. This object has different sections that describe different parts of the app.
- id: alert1
type: Alert
properties:
type: warning
showIcon: false
message: |
A good understanding of YAML is needed before starting with Lowdefy. If you don't have any experience using YAML, you can find a good introduction video <a href = "https://www.youtube.com/watch?v=cdLNKUoMc6c">here</a>.
- id: md2
type: MarkdownWithCode
properties:
content: |
The root schema for a Lowdefy app is:
- `lowdefy: string`: __Required__ - The Lowdefy version number that the app uses. This is required and cannot be a reference to another file.
- `name: string`: A name for the application.
- `version: string`: The version number of the app that you are building. This is optional and allows you indicate the version of your app.
- `license: string`: A [SPDX license ID](https://spdx.org/licenses/). You can use this to indicate the project's license if you are licensing your project under a specific software license. If you wish to indicate to others that you do not grant the right to use your project, you can optionally use `UNLICENSED` for this field. How you share your Lowdefy config is up to you.
- `cli: object`: An object with configuration for the CLI.
- `config: object`: An object with app configuration like the home page pageId.
- `auth: object` An object with auth configuration such as providers and an adapter.
- `global: object`: A data object that can be accessed anywhere in the app using the [`_global`](/_global) operator.
- `connections: object[]`: An array of [`connection`](/connections-and-requests) objects.
- `plugins: object[]`: An array of `plugin` objects to customize and add block types.
- `menus: object[]`: An array of menu objects.
- `pages: object[]`: An array of page objects.
Pages are made up of blocks. Blocks have the following basic schema:
- `id: string`: __Required__ - A unique identifier for a block.
- `type: string`: __Required__ - This is the block type identifier and defines what block to used.
- `properties: object`: All the settings passed to a block component.
- `blocks: array`: An array of blocks to render within this block.
Find the more detailed block schema [here](/blocks).
- id: alert2
type: Alert
properties:
type: info
showIcon: false
message: |
<h3> YAML file extensions </h3>
<p> Both files with the <code>.yaml</code> and <code>.yml</code> file extensions are supported as YAML files. </p>
<h3> JSON instead of YAML </h3>
<p> Since you can reference JSON files, you can build your app using JSON instead of YAML files. The <code>lowdefy.yaml</code> file needs to be a YAML file, but all other configuration can be in referenced JSON files. It also makes sense to use JSON instead of YAML if you are generating configuration using code. </p>
- id: md3
type: MarkdownWithCode
properties:
content: |
# Config
The config object has the following properties:
- `basePath: string`: Set the base path to serve the Lowdefy application from. This will route all pages under `https://example.com/<base-path>/<page-id>` instead of the default `https://example.com/<page-id>`. The basePath value must start with "/".
- `homePageId: string`: The pageId of the page that should be loaded when a user loads the app without a pageId in the url route. This is the page that is loaded when you navigate to `yourdomain.com`.
# Auth
TODO: Add auth things here
# Global
Any data that you wish to use in your app can be stored in the __global__ object, and accessed using the [`_global`](/_global) operator. This is a good place to store data or configuration that is used throughout the app, for example the url of a logo or configuration of a page, since then these are only written once, and can be updated easily.
The global object can also be modified using the [`SetGlobal`](/SetGlobal) action.
# Connections
In a Lowdefy app you can integrate with other services like API's or databases using `connections` and `requests`. Connections configure the connection settings to the service, and often contain parameters like connection strings, urls and secrets such as passwords or API keys. Requests are used to interact with the connection, for example inserting a data record, executing a query or calling a API end-point.
See more about how `connections` and `requests` are used together [here](/connections-and-requests).
# Plugins
TODO: Add plugin things here
# Menus
Menu objects are objects with links to pages. They are used by blocks like `PageSiderMenu` to render the links in the menu. If no menus are provided, a default menu is created, with links to all of the defined pages, and with their pageIds as menu item titles.
See more about how menu objects are used and defined [here](/menus).
# Pages
Pages in a Lowdefy app are actually just blocks, the building blocks of a Lowdefy app, with a few extra restrictions and features.
Each page should have an `id` that is unique among all pages in the app. Each page is served with the `pageId` as the url route. That is, if you create a page with id `page1`, it will be served at `domain.com/page1`.
If `properties.title` is set on a page block, the title will be set as the page title (This is the title displayed on the tabs in your browser).
Let's have a look at how to define a page and it's blocks. We can start with a simple page with an empty card block on it.
###### lowdefy.yaml
```yaml
lowdefy: LOWDEFY_VERSION
pages:
- id: page1
type: PageHeaderMenu
properties:
title: Page 1
blocks:
- id: content_card
type: Card
```
We can then add a title block and a paragraph block to our card so that it won't be so empty.
###### lowdefy.yaml
```yaml
lowdefy: LOWDEFY_VERSION
pages:
- id: page1
type: PageHeaderMenu
properties:
title: Page 1
blocks:
- id: content_card
type: Card
blocks:
- id: title
type: Title
properties:
content: Title
- id: paragraph
type: Paragraph
properties:
content: This is a paragraph on Page 1.
```
Let's add another card to our page and give it some blocks which will allow us to get input from the user.
###### lowdefy.yaml
```yaml
lowdefy: LOWDEFY_VERSION
pages:
- id: page1
type: PageHeaderMenu
properties:
title: Page 1
blocks:
- id: content_card
type: Card
blocks:
- id: title
type: Title
properties:
content: Title
- id: paragraph
type: Paragraph
properties:
content: This is a paragraph on Page 1.
- id: input_card
type: Card
blocks:
- id: text_input
type: TextInput
properties:
label:
title: Please Enter Your Name
- id: radio_selector
type: RadioSelector
properties:
label:
title: How Are You Feeling?
colon: false
options:
- label: Meh
value: 1
disabled: false
- label: Okay
value: 2
disabled: false
- label: Good
value: 3
disabled: false
- label: Great
value: 4
disabled: false
- label: Amazing Now That I'm Using Lowdefy
value: 5
disabled: false
```
In order to build our page further, we will need to add more blocks. Let's leave this page as is and add another page, with it's own card block containing a title block and a paragraph block.
###### lowdefy.yaml
```yaml
lowdefy: LOWDEFY_VERSION
pages:
- id: page1
type: PageHeaderMenu
properties:
title: Page 1
blocks:
- id: content_card
type: Card
blocks:
- id: title
type: Title
properties:
content: Title
- id: paragraph
type: Paragraph
properties:
content: This is a paragraph on Page 1.
- id: input_card
type: Card
blocks:
- id: text_input
type: TextInput
properties:
label:
title: Please Enter Your Name
- id: radio_selector
type: RadioSelector
properties:
label:
title: How Are You Feeling?
colon: false
options:
- label: Meh
value: 1
disabled: false
- label: Okay
value: 2
disabled: false
- label: Good
value: 3
disabled: false
- label: Great
value: 4
disabled: false
- label: Amazing Now That I'm Using Lowdefy
value: 5
disabled: false
- id: page2
type: PageHeaderMenu
properties:
title: Page 2
blocks:
- id: content_card
type: Card
blocks:
- id: title
type: Title
properties:
content: Title
- id: paragraph
type: Paragraph
properties:
content: This is a paragraph on Page 2.
```
In order to keep files neat and generally easier to read and understand, we suggest making use of references and templating.
# References and templates
References are used to split the configuration of an app into logically distinct files, and to reuse configuration in the app. References can be used almost anywhere in the configuration, as long as the configuration remains valid YAML.
Templating can be taken further by referencing [Nunjucks](https://mozilla.github.io/nunjucks/) template files. Nunjucks templates are useful since the template file does not need to be valid yaml before it is hydrated, and features like for-loops and if-statements can be used.
See more about references and templates [here](/references-and-templates).
# Lowdefy versions and version updates
Lowdefy is versioned using semantic versioning, with a three part version number, with the form `major.minor.patch`. Lowdefy is in the early stages of development and under active development, with new versions published on a regular basis.
To update the version of your app, change the `lowdefy` version field in the `lowdefy.yaml` file, and redeploy the app. You might also need to make some changes to your app configuration to be compatible with the new version.
Patch updates only contain fixes, and you should be safe to update to a patched version without any changes to your app. Since we are actively developing new features, most releases will be minor version updates, and patches won't be made to older versions.
Minor version changes include new features. At this stage, since the project is still in early development, they might also have minor breaking changes to individual blocks, actions, operators or connections. Please check the [changelog](https://github.com/lowdefy/lowdefy/blob/main/CHANGELOG.md) to see if any configuration changes are needed before updating.
Major version updates may include major breaking changes or architecture changes. You might need to make more changes to your configuration to be compatible with the new version. We don't intend to release major versions regularly, and try to minimize breaking changes.
As the project grows, we will release a long term support (LTS) version, that will continue to receive patches, but won't have any breaking changes.
- _ref:
path: templates/navigation_buttons.yaml
vars:
previous_page_title: The CLI
previous_page_id: cli
next_page_title: Context and State
next_page_id: context-and-state