mirror/lowdefy
2
0
Fork 0
mirror of https://github.com/lowdefy/lowdefy.git synced 2025-02-17 14:30:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1312 from lowdefy/deploy-docs

Browse Source 
Documentaion updates
This commit is contained in:
Gerrie van Wyk 2022-07-28 18:28:35 +02:00 committed by GitHub
commit e6261fefa9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
25 changed files with 615 additions and 1523 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
packages/docs/actions/Throw.yaml → packages/docs/actions/Break.yaml
View File

@ -15,9 +15,9 @@
_ref:
path: templates/actions.yaml.njk
vars:
pageId: Throw
pageTitle: Throw
filePath: actions/Throw.yaml
pageId: Break
pageTitle: Break
filePath: actions/Break.yaml
types: |
```
(params: {
@ -27,19 +27,21 @@ _ref:
}): void
```
description: |
The `Throw` action is used throw an error to the user and log to the console. If `throw: true`, the `Throw`
action will throw an error, and this will stop the execution of actions that are defined after it. If the action does not thrown, the `Throw` action will do nothing and the actions defined after it will be executed.
##### TODO: This page needs to be updated.
The `Break` action is used throw an error to the user and log to the console. If `throw: true`, the `Break`
action will throw an error, and this will stop the execution of actions that are defined after it. If the action does not thrown, the `Break` action will do nothing and the actions defined after it will be executed.
params: |
- `throw: boolean`: Throws an error and stops the action chain when `true` or continues the action chain when `false` or undefined.
- `throw: boolean`: Breaks an error and stops the action chain when `true` or continues the action chain when `false` or undefined.
- `message: string`: The error message to show to the user and log to the console if `throw: true`. This message can be overridden by setting the action's `messages.error`.
- `metaData: any`: Data to log to the console if `throw: true`.
examples: |
###### Throw with custom message:
###### Break with custom message:
```yaml
- id: throw
type: Throw
type: Break
params:
throw:
_eq:
@ -48,10 +50,10 @@ _ref:
message: Nooooooooooooooooo
```
###### Throw with metaData:
###### Break with metaData:
```yaml
- id: throw
type: Throw
type: Break
params:
throw:
_eq:
@ -64,7 +66,7 @@ _ref:
###### Override custom message:
```yaml
- id: throw
type: Throw
type: Break
messages:
error: Meh.
params:
@ -77,7 +79,7 @@ _ref:
###### Fail silently:
```yaml
- id: throw
type: Throw
type: Break
messages:
error: false
params:

16
packages/docs/actions/Message.yaml → packages/docs/actions/DisplayMessage.yaml
View File

@ -15,9 +15,9 @@
_ref:
path: templates/actions.yaml.njk
vars:
pageId: MessageAction
pageTitle: Message
filePath: actions/Message.yaml
pageId: DisplayMessage
pageTitle: DisplayMessage
filePath: actions/DisplayMessage.yaml
types: |
```
(params: {
@ -27,10 +27,10 @@ _ref:
}): void
```
description: |
The `Message` action is used to display a message to a user.
The `DisplayMessage` action is used to display a message to a user.
params: |
###### object
- `status: enum`: Message status type. Defaults to `success`. One of:
- `status: enum`: DisplayMessage status type. Defaults to `success`. One of:
- `success`
- `error`
- `info`
@ -42,7 +42,7 @@ _ref:
###### Display a success message:
```yaml
- id: success_message
type: Message
type: DisplayMessage
params:
content: Success
```
@ -50,7 +50,7 @@ _ref:
###### Display an info message that remains visible for 10 seconds:
```yaml
- id: info_message
type: Message
type: DisplayMessage
params:
content: Something happened
status: info
@ -60,7 +60,7 @@ _ref:
###### Display an error message that never disappears:
```yaml
- id: error_message
type: Message
type: DisplayMessage
params:
content: Something bad happened
status: error

23
packages/docs/actions/Fetch.yaml Normal file
View File

@ -0,0 +1,23 @@
# 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/actions.yaml.njk
vars:
pageId: Fetch
pageTitle: Fetch
filePath: actions/Fetch.yaml
types: ''
description: |
##### TODO: This page needs to be updated.

281
packages/docs/actions/JsAction.yaml
View File

@ -1,281 +0,0 @@
# 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/actions.yaml.njk
vars:
pageId: JsAction
pageTitle: JsAction
filePath: actions/JsAction.yaml
warning: |
SECURITY WARNING: The JsAction executes JavaScript inside your Lowdefy app. Insecure code can expose your app or data. Since Lowdefy doesn't validate your JavaScript, make sure that you only load trusted code.
types: |
```
(params: {
name: string,
args?: any[]
}): void
```
description: |
The `JsAction` action is used to call a custom JavaScript function which was loaded onto the page using the `window.lowdefy.registerJsAction()` method. This JavaScript function can be asynchronous. See [Custom Code](/custom-code) for more details on how to register a new JavaScript action.
The returned result of the JavaScript function is accessible through the [`_actions`](/_actions) operator for subsequent actions in the event action list.
#### JsAction function parameters
A `JsAction` function is called with a context object which includes all [`context` data objects](/context-and-state) as well as the list of `args` passed to the action.
```text
(context: {
actions: object,
contextId: string,
global: object,
input: object,
pageId: string,
requests: object,
state: object,
urlQuery: object,
user: object,
},
...args?: any[]): any
```
#### Using Lowdefy actions in a JsAction
The context passed to the custom JsAction function contains an object called `actions`. This object contains all the Lowdefy action functions like `SetState`, `Request`, and `CallMethod`. The functions can be called using the same parameters as when they are used directly in the Lowdefy configuration. Operators in these parameters are not evaluated.
params: |
###### object
- `name: string`: __Required__ - The registered name of the JavaScript function to call when the action is triggered.
- `args: any[]`: The array of positional arguments with which the JavaScript function should be called.
examples: |
##### Set a [Intercom](https://www.intercom.com/) user when a page is initialized:
```yaml
# lowdefy.yaml
name: intercom-example
lowdefy: '3.23.2'
app:
html:
appendBody: |
<script>
function setIntercomUser(context) {
window.intercomSettings = {
app_id: "{{ your_intercom_app_id }}",
name: context.user.name,
email: context.user.email,
};
}
window.lowdefy.registerJsAction('setIntercomUser', setIntercomUser);
</script>
<script>
(function(){var w=window;var ic=w.Intercom;if(typeof ic==="function"){ic('reattach_activator');
ic('update',w.intercomSettings);}else{var d=document;var i=function(){i.c(arguments);};i.q=[];
i.c=function(args){i.q.push(args);};w.Intercom=i;var l=function(){var s=d.createElement('script');
s.type='text/javascript';s.async=true;s.src='https://widget.intercom.io/widget/{{ your_intercom_app_id }}';
var x=d.getElementsByTagName('script')[0];x.parentNode.insertBefore(s,x);};
if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}})();
</script>
pages:
- id: home
type: PageHeaderMenu
events:
onInitAsync:
- id: set_intercom_user
type: JsAction # TODO:
params:
name: setIntercomUser
blocks:
# ...
```
##### Highlight search term returned by [MongoDB Search Highlight](https://docs.atlas.mongodb.com/reference/atlas-search/highlighting/):
Add a JavaScript file to highlight the search text by wapping the highlighted text with `<span style="background: yellow;">{{ value }}</span>`:
```js
// file: /public/highlightText.js
function highlightText(context, data) {
return data.map((item) => {
item.highlights.forEach((light) => {
const paths = light.path.split('.');
const key = paths[paths.length - 1];
paths.pop();
let res = item;
paths.forEach((key) => {
res = res[key];
});
res[key] = light.texts.reduce((acc, obj) => {
if (obj.type === 'hit') {
return acc.concat('<span style="background: yellow;">', obj.value, '</span>');
}
return acc.concat(obj.value);
}, '');
});
return item;
});
}
export default highlightText;
```
Import custom JavaScript modules:
```js
// file: /public/modules.js
import highlightText from './highlightText.js';
window.lowdefy.registerJsAction('highlightText', highlightText);
````
Lowdefy setup:
```yaml
# file: lowdefy.yaml
name: text-highlight-example
lowdefy: '3.23.2'
app:
html:
# Load the custom modules into the index.html head tag.
appendHead: |
<script type="module" src="/public/modules.js"></script>
connections:
- id: products
type: MongoDBCollection
properties:
collection: products
databaseUri:
_secret: MDB_URI
pages:
- id: home
type: PageHeaderMenu
requests:
- id: search_products
type: MongoDBAggregation
connectionId: products
properties:
pipeline:
_array.concat:
- - $search:
compound:
should:
- text:
query:
_string.concat:
- '*'
- _state: search.input
- '*'
path:
- title
- description
- wildcard:
query:
_string.concat:
- '*'
- _state: search.input
- '*'
path:
- title
- description
allowAnalyzedField: true
highlight:
path:
- title
- description
- $addFields:
score:
$meta: searchScore
highlights:
$meta: searchHighlights
blocks:
- id: search.input
type: TextInput
properties:
title: Type to search products
prefix: AiOutlineSearch
events:
onChange:
- id: get_search # get search_products query for search.input
type: Request
params: search_products
- id: apply_highlight # apply the highlight transformation to the request data.
type: JsAction # TODO:
params:
name: highlightText
args:
- _request: search_products
- id: set_state # set the response of the apply_highlight action to state
type: SetState
params:
found_products:
_actions: apply_highlight.response
- id: product_results
type: Html
properties:
html:
_nunjucks:
template: |
<ul>
{% for item in found_products %}
<li>{{ item.title | safe }} - {{ item.description | safe}}</li>
{% endfor %}
</ul>
on:
found_products:
_state: found_products
```
NOTE: For this example to work, you will need a `products` collection in your MongoDB database, populated with `{title: '...', description: '...'}` data objects including the following search index on the `products` collection:
```json
{
"mappings": {
"dynamic": true,
"fields": {
"title": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
```
##### Use Lowdefy SetState action:
```js
// file: /public/theAnswer.js
function theAnswer({actions}) {
// Think for a while...
return actions.SetState({ answer: 42 })
}
export default theAnswer;
```
##### Use Lowdefy Request action to loop over a list of requests:
```js
// file: /public/loopRequests.js
function loopRequests({ actions }, ...requestIds) {
return Promise.all(requestIds.map((id) => actions.Request(id)));
}
export default loopRequests;
```
```yaml
id: call_all_requests
type: Button
events:
onClick:
- id: loop_requests
type: JsAction # TODO:
params:
name: loopRequests
args:
- request_1
- request_2
- request_3
```

84
packages/docs/actions/Notification.yaml
View File

@ -1,84 +0,0 @@
# 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/actions.yaml.njk
vars:
pageId: NotificationAction
pageTitle: Notification
filePath: actions/Notification.yaml
types: |
```
(params: {
status?: enum,
duration?: number,
message?: string,
description?: string,
placement?: enum,
bottom?: number,
top?: number
}): void
```
description: |
The `Notification` action is used to display a notification message to a user.
params: |
###### object
- `status: enum`: Message status type. Defaults to `success`. One of:
- `success`
- `error`
- `info`
- `warning`
- `loading`.
- `duration: number`: Time in seconds before the notification disappears. When set to 0 or null, it will never be closed automatically. The default is 5.
- `message: string`: The title of notification. Default is "Success".
- `description: sttring`: The content of the notification.
- `placement: enum`: Position of the notification. Default is `bottomRight`. Can be one of:
- `topLeft`
- `topRight`
- `bottomLeft`
- `bottomRight`
- `bottom: number`: Distance from the bottom of the viewport, when placement is `bottomRight`or `bottomLeft` in pixels. The default is 24.
- `top: number`: Distance from the bottom of the viewport, when placement is `topRight`or `topLeft` in pixels. The default is 24.
examples: |
###### Display a success notification:
```yaml
- id: success
type: Notification
params:
message: Hello
```
###### Display an info notification with a description:
```yaml
- id: info
type: Notification
params:
message: Something happened
status: info
description: This is a longer description of the thing that happened, so that you know why it happened.
duration: 10
placement: topRight
```
###### Display an warning notification that does not disappear until closed:
```yaml
- id: warning
type: Notification
params:
message: Something bad might happen.
status: warning
description: This is a longer description of the thing that happened, so that you know why it happened.
duration: 0
placement: topRight
```

2
packages/docs/concepts/cli.yaml
View File

@ -24,6 +24,8 @@ _ref:
type: MarkdownWithCode
properties:
content: |
##### TODO: This page needs to be updated.
The Lowdefy CLI is used to develop a Lowdefy app locally, and to build Lowdefy apps for deployment.
We recommend running the CLI using `npx`, to always use the latest version:

2
packages/docs/concepts/context-and-state.yaml
View File

@ -24,6 +24,8 @@ _ref:
type: Markdown
properties:
content: |
##### TODO: This page needs to be updated.
#### TLDR
- The first block on a page must be a `context` category block.
- A page can have multiple `context` blocks.

191
packages/docs/concepts/custom-blocks.yaml
View File

@ -1,191 +0,0 @@
# 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: custom-blocks
pageTitle: Custom Blocks
section: Concepts
filePath: concepts/custom-blocks.yaml
content:
- id: warning
type: Alert
properties:
message: |
SECURITY WARNING: Blocks execute JavaScript inside your Lowdefy app. Insecure code can expose your app or data. Make sure that you only load blocks from a trusted source.
type: warning
- id: md1
type: MarkdownWithCode
properties:
content: |
Blocks in Lowdefy are simple, most often state-less, [React components](https://reactjs.org/docs/components-and-props.html). Lowdefy uses [webpack module federation](https://webpack.js.org/concepts/module-federation/) to implement a micro front-end strategy. This means blocks are imported at load time, and not part of the Lowdefy app build.
The decoupling of blocks provides the considerable advantages:
- Block developers can extend the UI capabilities of Lowdefy by building blocks for the community to utilize.
- Lowdefy app developers can use community blocks to experiment and extend their apps.
- Lowdefy blocks are simple, most often stateless React components, thus blocks can be developed quickly and can be used inside Lowdefy apps with ease.
- The build process is simple and fast since you only build the code for your block, and not the entire application.
- The Lowdefy engine takes care off the application state, the the block only has to concern itself with a easy application interface.
## Using Custom Blocks
To use a custom block type inside a Lowdefy app, configure the `types` object in the root of the Lowdefy config. For example to use a AmCharts block we can add a `AmChartsXY` type to the `types`.
```yaml
name: dashboard-app
lowdefy: 3.23.2
types:
AmChartsXY:
url: https://blocks-cdn.lowdefy.com/v3.10.1/blocks-amcharts/meta/AmChartsXY.json
# ...
pages:
- id: dashboard
type: PageHeaderMenu
blocks:
- id: my_chart
type: AmChartsXY
properties:
#...
#...
```
By default Lowdefy build apps with a set of pre-configured, default block types to make it easier to build apps, for example using [`Button`](/Button), [`TextInput`](/TextInput), [`Box`](/Box), etc. All the blocks documented in the Lowdefy docs are default types. We will continue to build out this list of default blocks to make it as easy as possible to build excellent feature rich apps.
It is possible to overwrite the default a block type by simply defining a url for the default type in the `types` object. This is especially useful when you need to use a older version of a block, or would like to do something unique.
#### Examples of Custom Blocks
##### AmCharts:
[AmCharts](https://www.amcharts.com/) enables you to render powerful javascript charts. We have created the [AmCharts Lowdefy blocks](https://github.com/lowdefy/blocks-amcharts) making it easy to use highly customizable charts in your apps.
##### Ag-Grid:
[Ag-Grid](https://www.ag-grid.com/) enables you to render feature rich tables. We have created the [AgGrid Lowdefy blocks](https://github.com/lowdefy/blocks-aggrid) making it easy to use advanced tables in your apps.
## Steps to develop a custom block
#### 1. Clone the blocks template repository
To develop a custom block, first clone the [Lowdefy blocks template repository](https://github.com/lowdefy/blocks-template). This template provides a project structure for building a custom block. This structure can be modified to your preferences with the following exceptions:
- Keep the webpack configuration to ensure your custom block works with Lowdefy block module federation.
- Blocks need meta data in the block schema format which Lowdefy uses to interpret how to render your block.
#### 2. Start your local block server
Once the repository is cloned, `yarn install` the block dependencies. Then start the local block server by running `yarn start`. The default is to start you block server on `http://localhost:3002`. Open `http://localhost:3002/meta/DisplayBlock.json` in your browser and confirm the the block meta data is served.
You can create multiple blocks in the same repository, or run multiple block servers from different block repositories. Use `yarn start --port {{ port_number }}` when you need to run multiple block servers.
#### 3. Configure your block types
In your `lowdefy.yaml` file, add your custom block type to the `types` object with the local path.
```yaml
name: dashboard-app
lowdefy: 3.23.2
types:
MyCustomBlock:
url: http://localhost:3002/meta/MyCustomBlock.json
# ...
```
You can then test your block locally by running `npx lowdefy@latest dev` to develop your Lowdefy app together with your custom block.
#### 4. Code your Lowdefy block
A Lowdefy block consist of two files, your schema file and your React component. With Lowdefy we try to keep blocks stateless and let the Lowdefy engine mange application state.
For most applications this is fine and it simplifies the block logic, the result is "smaller" blocks and more flexibility to the Lowdefy app builder. It is up to the block developer to decide how to balance the trade off between configurability and complexity of the block. For example, it might be better for a UI elements like a Calender to be state-full and packaged as one piece, rather than to break the Calender up into various smaller blocks, that Lowdefy app developers need to piece together. With that said, it is worth mentioning that every time the block properties changes, Lowdefy will rerender the entire block, this can have a performance impact when blocks become large and complex.
### Block schema definition
- `category: enum`: How this block should be rendered in the Lowdefy app. Can be either `display`, `input`, `container`, `context` or `list`.
- `valueType: enum`: For blocks of the `input` block category, Lowdefy enforces a value type in `state`. This can be either a `boolean`, `number`, `string`, `object` or `array`. Lowdefy provides a default value for the block. This is usually `null`, but is `false` for boolean blocks, and the empty array, `[]`, for array blocks.
- `schema: object`: Provide a valid [JSON-Schema](https://json-schema.org/) definition for the block `properties` and `events`.
# TODO: add icon.
### Block React Component Props
The React component will receive the following props:
- `basePath: string`: The base path setting for the application. This variable is used to prefix route paths for example `${basePath}/logo-square-light-theme.png`. The default base path is ''.
- `blockId: string`: The block's id within the Lowdefy app, this is useful for setting a unique `id` on DOM elements.
- `components: object`: Helper React components that are exposed to blocks to use internally.
- `Icon`: component`: Lowdefy standard Icon React component to render build in icons.
- `Link`: component`: Lowdefy standard Link React component used as links to pages or external urls. The following props apply:
- `ariaLabel: string`: Arial-label to apply to link tag.
- `back: boolean`: When the link is clicked, trigger the browser back.
- `home: boolean`: When the link is clicked, route to the home page.
- `input: object`: When the link is clicked, pass data as the input object to the next Lowdefy page. Can only be used with pageId link and newTab false. See [Input]( TODO: Link to input page? ).
- `newTab: boolean`: When the link is clicked, open the page in a new browser tab.
- `pageId: string`: When the link is clicked, route to the provided Lowdefy page.
- `rel: string`: The relationship of the linked URL as space-separated link types.
- `replace: boolean`: Prevent adding a new entry into browser history by replacing the url instead of pushing into history. Can only be used with pageId link and newTab false.
- `scroll: boolean`: Disable scrolling to the top of the page after page transition. Can only be used with pageId link and newTab false.
- `url: string`: When the link is clicked, route to an external url.
- `urlQuery: object`: When the link is clicked, pass data as a url query to the next page. See [url query]( TODO: Link to url query page? ).
- `content: object`: Passed to `container` and `context` block categories. The `content` object with methods to render sub blocks into content areas. The method name is the same as the area key, for example, 'content.content()` renders a blocks default `content` area.
- `events: object`: All events defined on the block in the Lowdefy app config.
- `[event_key]: object`: Event keys gives a handle name to the event details.
- `loading: boolean`: True while the list of actions are being executed.
- `actions: actionObjects[]`: The list of [Lowdefy action objects](https://docs.lowdefy.com/events-and-actions) which will be evaluated by the Lowdefy engine.
- `history: object[]`: A list of objects logging the event calls and responses.
- `blockId: string`: The block id from which the event was called.
- `endTimestamp: datetime`: Timestamp for when the event was completed.
- `event: object`: The event object passed to the event.
- `eventName: string`: The event name which which triggerEvent was called.
- `success: boolean`: True if all actions for the event executed without throwing any errors.
- `startTimestamp: datetime`: Timestamp for when the event was started.
- `responses: object`: The list of action responses, where the object key is equal to the action id.
- `{{ key }}: string`:
- `type: string`: The type of action called.
- `error: Error`: If the action throw an error.
- `index: number`: Index of the action in the event array.
- `response: any`: The returned result of the action.
- `skipped: boolean`: True if the action was skipped.
- `loading: boolean`: True while loading is activated for the block.
- `methods: object`: All application methods built into Lowdefy, available for the block.
- `makeCssClass(cssObject | cssObject[]): string`: This methods creates a css class for the block to apply to DOM elements. Css classes are created using [Emotion](https://emotion.sh/docs/introduction). If a list of cssObject are given the cssObjects are shallow merged with the preceding objects properties being overwritten by the latter. Any valid css style object can be passed, including media queries. Default media queries are built in:
- `xs?: object`: Css object applied for screen media with max width of 576px.
- `sm?: object`: Css object applied for screen media with min width of 576px.
- `md?: object`: Css object applied for screen media with min width of 768px.
- `lg?: object`: Css object applied for screen media with min width of 992px.
- `xl?: object`: Css object applied for screen media with min width of 1200px.
- `xxl?: object`: Css object applied for screen media with min width of 1600px.
- `registerEvent(event: { name: string, actions: actionObjects[] })`: This method can be used to register internal actions for the block to trigger, and overwrites the user config if user defined actions are provided for the same event name.
- `registerMethod(methodName: string, fn(any))`: This method allows the block developed to expose a method to the Lowdefy app developer via the [`CallMethod`](https://docs.lowdefy.com/CallMethod) action. When the method name for the block id is triggered via a `CallMethod` action, `fn` is evaluated.
- `triggerEvent({name: string, event?: any })`: This methods triggers a event when called, like `onClick` for when a button is clicked. Optionally, event data can be passed which will be available inside the event actions through the [`_event`](https://docs.lowdefy.com/_event) operator.
- `properties: object`: The properties object provides all the block settings defined in the Lowdefy config, operators can be used when defining block properties and evaluated operators are passed to the block. When the evaluated result of these properties change, the block rerenders to display the updated block.
- `required: boolean`: For blocks of the `input` category, whether or not a input value is required. Required can be defined by operators and the evaluated result is passed to the block. The [`Validate`](https://docs.lowdefy.com/Validate) action will check if the required values are present else raise `validation` errors and suspend further block actions in the event queue.
- `validation: object`: For blocks of the `input` category, the validation property provides result of `Validate` relevant relevant to the specific block. See [block validation](/blocks) for more details.
- `status: enum`: The validation status result. Can be `error`, `success` or `warning`. Only validation which results in an `error` status will suspend further block actions in the event queue.
- `errors: string[]`: The list of error messaged raised whiled block validation was evaluated, for this block.
- `warnings: string[]`: The list of warnings messaged raised whiled block validation was evaluated, for this block.
## Deploying Custom Blocks
Both the block metadata and block React component need to be built by webpack and hosted on a publicly accessible static file server. Any Lowdefy app can then load and use the block. You also need to set the `remoteEntryUrl` in `webpack.prod.js` in order to build the correct block meta data, make sure the URL is pointing to where your block is hosted.
The easiest way to host your custom block is the deploy the custom block to [npm](https://www.npmjs.com/) and [Unpkg](https://unpkg.com/) will automatically host your block for you on their CDN. Although this option is easy, the cache settings for Unpkg can result in longer load times in some cases which can result in a unreliable user experience. It is thus best to deploy you blocks to your own static file servers.
We are working on a Lowdefy blocks CDN to improve this developer experience in the future.
- _ref:
path: templates/navigation_buttons.yaml
vars:
previous_page_title: Custom Code
previous_page_id: custom-code
next_page_title: User authentication
next_page_id: users-introduction

123
packages/docs/concepts/custom-code.yaml
View File

@ -29,11 +29,12 @@ _ref:
- id: md1
type: MarkdownWithCode
properties:
# TODO: Remove JsAction reference.
content: |
##### TODO: This page needs to be updated.
Lowdefy runs as a single page web app (SPA). 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` to of the default `index.html` page.
The content loaded into the `head` and `body` tag can be any valid HTML, most often `script` tags are loaded to register a new [`JsAction`](/JsAction) or [`_js`](/_js) operator. However, third party code can also be imported, for example Google Analytics, Intercom, etc. 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 easily be hosted from the [Lowdefy public folder](/hosting-files).
The content loaded into the `head` and `body` tag can be any valid HTML. Third party code can be imported, for example Google Analytics, Intercom, etc. 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 easily be hosted from the [Lowdefy public folder](/hosting-files).
> __Warning__: Lowdefy implements the [Ant design](https://ant.design/) UI component framework for app layout and most blocks, thus the default Ant Design CSS is loaded for all Lowdefy apps. Take caution not to unintentionally overwrite existing style settings and classes which can result in a degraded user experience.
@ -72,126 +73,8 @@ _ref:
<!-- End Google Analytics -->
# ...
```
###### Load, register and trigger a custom `JsAction` from code in the app `public` folder:
This example fetches a list of Todos from [{JSON}placeholder](https://jsonplaceholder.typicode.com/), and updates [state](/context-and-state).
1) First, add the JavaScript code to the `public` folder and resister the `JsAction`:
```js
// /public/fetchTodos.js
function async fetchTodos(context, numItems, skip) {
const data = await fetch('https://jsonplaceholder.typicode.com/todos');
const todos = await data.json();
return todos.slice(skip, skip + numItems);
}
// Register the JsAction for the Lowdefy app to use.
window.lowdefy.registerJsAction('fetchTodos', fetchTodos);
```
2) Import the JavaScript as a module into the page:
```html
<!-- /header_modules.html -->
<script type="module" src="/public/fetchTodos.js"></script>
```
3) Set load the custom code into the app header and trigger the action on page load:
```yaml
# /lowdefy.yaml
name: json-todos
lowdefy: 3.23.2
app:
html:
appendHead:
_ref: header_modules.html # Load the custom HTML into the header.
pages:
- id: todos
type: PageHeaderMenu
events:
onInit:
- id: get_todos
type: JsAction # TODO:
params:
name: fetchTodos # Trigger the custom JavaScript action.
args:
- 10 # numItems
- 0 # skip
- id: set_todos
type: SetState
params:
todos:
# Set the response of the get_todos action to state.
_actions: get_todos.response
# ...
```
## Loading and registering a [`_js`](/_js) operator
Similar to the loading custom JavaScript actions, custom JavaScript operators can also be loaded. In order for the Lowdefy app engine to execute a custom JavaScript [operator](/operators), the JavaScript code for the operator must be loaded onto the page and registered using the `registerJsOperator` method available on the browser [`window`](https://developer.mozilla.org/en-US/docs/Web/API/window) object by calling `window.lowdefy.registerJsOperator(name: string, action: function)`.
All `_js` functions must be synchronous.
#### Examples
###### Load, register and use a custom `_js` operator from code in the app `public` folder:
This example uses a `_js` operator to remove all duplicates from a list of names.
1) First, add the JavaScript code to the `public` folder and resister the `_js` operator:
```js
// /public/foo_operators.js
function removeDuplicates(items) {
return [ ...new Set(items) ];
}
// Register the removeDuplicates function as a _js.deduplicate operator.
window.lowdefy.registerJsOperator('deduplicate', removeDuplicates);
```
2) Import the JavaScript as a module into the page:
```html
<!-- /header.html -->
<script type="module" src="/public/foo_operators.js"></script>
```
3) Set load the custom code into the app header and use the new operator on the page:
```yaml
# /lowdefy.yaml
name: operator-example
lowdefy: 3.23.2
app:
html:
appendHead:
_ref: header.html # Load the custom HTML into the header.
pages:
- id: some_names
type: PageHeaderMenu
blocks:
- id: names
type: ButtonSelector
properties:
title: Select your new friend
options:
# use the removeDuplicates function and pass a list of names as a function argument
_js.deduplicate:
- - Anne
- Sam
- Joe
- Micheal
- Sam
- Steven
- Anne
- Pepper
# ...
```
------
Custom code provides an easy way to extent the logic functionality of Lowdefy apps. However, to extend the UI capabilities beyond the existing features provided by the default Lowdefy blocks, custom blocks can be loaded onto apps.
- _ref:
path: templates/navigation_buttons.yaml
vars:
previous_page_title: Lists
previous_page_id: lists
next_page_title: Custom Blocks
next_page_id: custom-blocks

2
packages/docs/concepts/overview.yaml
View File

@ -24,6 +24,8 @@ _ref:
type: Markdown
properties:
content: |
##### TODO: This page needs to be updated.
Lowdefy apps are written as YAML configuration files. These files can be managed in source control, and multiple apps can be deployed with the same configuration. To serve an app, the configuration first needs to be built using the Lowdefy CLI. A Lowdefy server can then serve the build artifacts.
You need to host your own Lowdefy server. We want to enable you to host a Lowdefy anywhere and Lowdefy was designed to run in a serverless environment. Currently, you can host Lowdefy apps on Netlify, and as a Docker container.

128
packages/docs/deployment/aws-lambda.yaml
View File

@ -1,128 +0,0 @@
# 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: aws-lambda
pageTitle: Deploy with AWS Lambda
section: Deployment
filePath: deployment/aws-lambda.yaml
content:
- id: md1
type: Markdown
properties:
content: |
Lowdefy apps can be deployed to AWS Lambda serverless functions by using the [lowdefy/lowdefy-aws-lambda](https://hub.docker.com/repository/docker/lowdefy/lowdefy-aws-lambda) Docker images. These images contain a Lowdefy app server. To deploy to AWS Lambda a new image that contains the app configuration, based on the Lowdefy base image, should be built. This image should then be pushed to a private AWS ECR registry. From there it can be used to create a Lambda function.
The [serverless framework](https://www.serverless.com) can be used to simplify the deployment. The serverless framework create a ECR registry if it does not exist, build the Docker image, push to the registry and deploy an AWS Lambda function with a API Gateway HTTP api integration.
An example can be found in the [lowdefy-example-aws-lambda](https://github.com/lowdefy/lowdefy-example-aws-lambda) repository.
## Deploying to AWS Lambda
### Requirements
- The [AWS CLI](https://aws.amazon.com/cli/) should be installed and authenticated.
- You should have [Docker](https://docs.docker.com/get-docker/) installed.
### Step 1 - Create a Dockerfile
Create a file called `Dockerfile` in your project repository:
```
FROM node:14-buster AS build
# Set working directory and node user
WORKDIR /home/node/lowdefy
RUN chown node:node /home/node/lowdefy
USER node
# Copy app config, and change ownership of files to "node" user
COPY --chown=node:node . .
# Build the Lowdefy config using the Lowdefy CLI
RUN npx lowdefy@3.23.2 build
# Use the correct Lowdefy base image
FROM lowdefy/lowdefy-aws-lambda:3.23.2
# Copy build output from build stage
COPY --from=build /home/node/lowdefy/.lowdefy/build ./build
# Copy contents of public directory into image
COPY ./public ./public
# Lambda handler
CMD [ "dist/server.handler"]
```
- id: warning_update_dockerfile
type: Alert
properties:
type: warning
icon: AiFillWarning
description: When updating your app to a new Lowdefy version, make sure to update the Lowdefy version in the Dockerfile
- id: md2
type: Markdown
properties:
content: |
### Step 2 - Create a `.dockerignore` file
Create a file called `.dockerignore` in your project repository:
```
.lowdefy/**
.serverless/**
.env
```
### Step 3 - Create a serverless.yaml file
Create a file called `serverless.yaml` in your project repository:
```
service: lowdefy-example-aws-lambda
frameworkVersion: '2'
provider:
name: aws
region: us-east-1
ecr:
images:
lowdefy:
path: .
file: Dockerfile
functions:
lowdefy-server:
image: lowdefy
name: lowdefy-example-aws-lambda-${opt:stage}
# Set secrets as environment variables here
# environment:
# LOWDEFY_SECRET_MY_SECRET: ${env:LOWDEFY_SECRET_MY_SECRET}
events:
- httpApi: '*'
```
### Step 4 - Deploy to AWS
Deploy to AWS by running:
```
npx serverless deploy --verbose --conceal --stage dev
```

139
packages/docs/deployment/docker.yaml
View File

@ -24,95 +24,96 @@ _ref:
type: Markdown
properties:
content: |
The [official Lowdefy Docker](https://hub.docker.com/repository/docker/lowdefy/lowdefy) images can be found on Docker Hub.
##### TODO: This page needs to be updated.
# The [official Lowdefy Docker](https://hub.docker.com/repository/docker/lowdefy/lowdefy) images can be found on Docker Hub.
Examples of Docker configuration can be found in the [example repository](https://github.com/lowdefy/lowdefy-example-docker).
# Examples of Docker configuration can be found in the [example repository](https://github.com/lowdefy/lowdefy-example-docker).
The Lowdefy Docker images contain a Lowdefy server. The configuration of the Lowdefy app can either be built into a new image based on the Lowdefy image, or the configuration read from the file system, usually provided as a volume.
# The Lowdefy Docker images contain a Lowdefy server. The configuration of the Lowdefy app can either be built into a new image based on the Lowdefy image, or the configuration read from the file system, usually provided as a volume.
The Lowdefy server can be configured using the following environment variables:
# The Lowdefy server can be configured using the following environment variables:
- `LOWDEFY_BASE_PATH`: Set the base path to serve the Lowdefy application from. This will serve the application under `https://example.com/<base-path>`instead of `https://example.com`, and all pages under `https://example.com/<base-path>/<page-id>` instead of the default `https://example.com/<page-id>`.
- `LOWDEFY_SERVER_BUILD_DIRECTORY`: The directory of the built Lowdefy configuration (The output of `lowdefy build`, usually found at `./.lowdefy/build` in your project repository). The default is `./build` (or `/home/node/lowdefy/build`).
- `LOWDEFY_SERVER_PUBLIC_DIRECTORY`: The directory of the public assets to be served. The default is `./public` (or `/home/node/lowdefy/public`).
- `LOWDEFY_SERVER_PORT`: The port (inside the container) at which to run the server. The default is `3000`.
# - `LOWDEFY_BASE_PATH`: Set the base path to serve the Lowdefy application from. This will serve the application under `https://example.com/<base-path>`instead of `https://example.com`, and all pages under `https://example.com/<base-path>/<page-id>` instead of the default `https://example.com/<page-id>`.
# - `LOWDEFY_SERVER_BUILD_DIRECTORY`: The directory of the built Lowdefy configuration (The output of `lowdefy build`, usually found at `./.lowdefy/build` in your project repository). The default is `./build` (or `/home/node/lowdefy/build`).
# - `LOWDEFY_SERVER_PUBLIC_DIRECTORY`: The directory of the public assets to be served. The default is `./public` (or `/home/node/lowdefy/public`).
# - `LOWDEFY_SERVER_PORT`: The port (inside the container) at which to run the server. The default is `3000`.
- id: warning_update_dockerfile
type: Alert
properties:
type: warning
icon: AiFillWarning
description: When updating your app to a new Lowdefy version, make sure to update the Lowdefy version in the Dockerfile
# - id: warning_update_dockerfile
# type: Alert
# properties:
# type: warning
# icon: AiFillWarning
# description: When updating your app to a new Lowdefy version, make sure to update the Lowdefy version in the Dockerfile
- id: md2
type: Markdown
properties:
content: |
# Building a Lowdefy app image
# - id: md2
# type: Markdown
# properties:
# content: |
# # Building a Lowdefy app image
To build the configuration into an image, the following Dockerfile can be used:
```text
FROM node:14-buster AS build
# To build the configuration into an image, the following Dockerfile can be used:
# ```text
# FROM node:14-buster AS build
# Set working directory and node user
WORKDIR /home/node/lowdefy
# # Set working directory and node user
# WORKDIR /home/node/lowdefy
RUN chown node:node /home/node/lowdefy
# RUN chown node:node /home/node/lowdefy
USER node
# USER node
# Copy app config and change ownership of files to "node" user
COPY --chown=node:node . .
# # Copy app config and change ownership of files to "node" user
# COPY --chown=node:node . .
# Build the Lowdefy config using the Lowdefy CLI
RUN npx lowdefy@3.23.2 build
# # Build the Lowdefy config using the Lowdefy CLI
# RUN npx lowdefy@3.23.2 build
# Use the correct Lowdefy base image
FROM lowdefy/lowdefy:3.23.2
# # Use the correct Lowdefy base image
# FROM lowdefy/lowdefy:3.23.2
# Copy build output from build stage
COPY --from=build --chown=node:node /home/node/lowdefy/.lowdefy/build ./build
# # Copy build output from build stage
# COPY --from=build --chown=node:node /home/node/lowdefy/.lowdefy/build ./build
# Copy contents of public directory into image
COPY --chown=node:node ./public ./public
# # Copy contents of public directory into image
# COPY --chown=node:node ./public ./public
# Run the server on start
CMD ["node", "./dist/server.js"]
```
# # Run the server on start
# CMD ["node", "./dist/server.js"]
# ```
with a `.dockerignore` file:
# with a `.dockerignore` file:
```
.lowdefy/**
.env
```
# ```
# .lowdefy/**
# .env
# ```
An image can be built by running:
```
docker build -t <tag> .
```
# An image can be built by running:
# ```
# docker build -t <tag> .
# ```
The container can be run by:
```
docker run -p 3000:3000 <tag>
```
# The container can be run by:
# ```
# docker run -p 3000:3000 <tag>
# ```
Docker compose can also be used. Use a `docker-compose.yaml` file:
```
version: "3.8"
services:
lowdefy:
build: .
ports:
- "3000:3000"
```
# Docker compose can also be used. Use a `docker-compose.yaml` file:
# ```
# version: "3.8"
# services:
# lowdefy:
# build: .
# ports:
# - "3000:3000"
# ```
To build the image, run:
```
docker compose build
```
# To build the image, run:
# ```
# docker compose build
# ```
To run the app, run:
```
docker compose up
```
# To run the app, run:
# ```
# docker compose up
# ```

69
packages/docs/deployment/netlify.yaml
View File

@ -1,69 +0,0 @@
# 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: netlify
pageTitle: Deploy to Netlify
section: Deployment
filePath: deployment/netlify.yaml
content:
- id: md1
type: MarkdownWithCode
properties:
content: |
Lowdefy apps can be deployed to [Netlify](https://www.netlify.com). Netlify integrates with git providers to automatically deploy your app when you merge changes into the main branch of your repository and deploy previews of pull requests. On your Netlify deployment you can set environment variables, manage custom domains and more.
## How to Deploy to Netlify
#### Step 1
Your project will need to be hosted as a Github repository.
#### Step 2
Link your Github project to Netlify.
- Once logged in to Netlify, click the "New site from git" button.
- Choose Github, and authorize Netlify to access your repositories.
- Select your repository.
> If your repository isn't found, click "Configure Netlify on Github", and give Netlify access to your repository.
#### Step 3
Configure your Netlify deployment.
- Set your build command to `npx lowdefy@3 build-netlify`.
- Set your publish directory to `.lowdefy/publish`.
#### Step 4
Configure the Lowdefy server.
- Click the "Advanced build settings" button.
- Set the functions directory to `.lowdefy/functions`.
#### Step 5
Deploy your site.
- Click "Deploy site"
On the "Site overview" tab you will find your site url.
#### Step 6
To set Lowdefy secrets, go to "Site settings", then "Build and deploy" in the left menu. Scroll down and select "Edit variables" in the "Environment" section. Here you can set the `LOWDEFY_SECRET_` environment variables.

109
packages/docs/deployment/node-server.yaml
View File

@ -24,88 +24,89 @@ _ref:
type: Markdown
properties:
content: |
A production Lowdefy server that runs using Node.js is published on npm as [@lowdefy/server-node](https://www.npmjs.com/package/@lowdefy/server-node).
##### TODO: This page needs to be updated.
## Running the server
# A production Lowdefy server that runs using Node.js is published on npm as [@lowdefy/server-node](https://www.npmjs.com/package/@lowdefy/server-node).
### Step 1 - Create a `package.json` file
# ## Running the server
To run the server in a Lowdefy project, first initialise a Node.js project by creating a `package.json` file in the root of your project. To do this, you can run
# ### Step 1 - Create a `package.json` file
```
npm init
```
# To run the server in a Lowdefy project, first initialise a Node.js project by creating a `package.json` file in the root of your project. To do this, you can run
### Step 2 - Add the `@lowdefy/server-node` package to your project as a dependency
# ```
# npm init
# ```
To add the server as a dependency, run
# ### Step 2 - Add the `@lowdefy/server-node` package to your project as a dependency
```
npm install @lowdefy/server-node --save --save-exact
```
# To add the server as a dependency, run
### Step 3 - Add the Lowdefy CLI to you project as a dev dependency.
# ```
# npm install @lowdefy/server-node --save --save-exact
# ```
To add the server as a dependency, run:
# ### Step 3 - Add the Lowdefy CLI to you project as a dev dependency.
```
npm install lowdefy --save-dev --save-exact
```
# To add the server as a dependency, run:
### Step 4 - Add the `build` and `start` scripts.
# ```
# npm install lowdefy --save-dev --save-exact
# ```
Add the following to the `scripts` section in your `package.json` file:
# ### Step 4 - Add the `build` and `start` scripts.
```json
"scripts": {
"init": "lowdefy init",
"build": "lowdefy build",
"start": "lowdefy-server"
},
```
# Add the following to the `scripts` section in your `package.json` file:
### Step 5 - Init a Lowdefy project
# ```json
# "scripts": {
# "init": "lowdefy init",
# "build": "lowdefy build",
# "start": "lowdefy-server"
# },
# ```
Run:
# ### Step 5 - Init a Lowdefy project
```
npm run init
```
# Run:
### Step 6 - Add the public files:
# ```
# npm run init
# ```
Create a folder called `public` in your project directory and add the Lowdefy public files found [here](https://github.com/lowdefy/lowdefy/tree/main/packages/shell/src/public) (or add your own logos and files).
# ### Step 6 - Add the public files:
### Step 7 - Build the Lowdefy project
# Create a folder called `public` in your project directory and add the Lowdefy public files found [here](https://github.com/lowdefy/lowdefy/tree/main/packages/shell/src/public) (or add your own logos and files).
Build the Lowdefy configuration files in the project by running:
# ### Step 7 - Build the Lowdefy project
```
npm run build
```
# Build the Lowdefy configuration files in the project by running:
### Step 8 - Start the server
# ```
# npm run build
# ```
To start the server, run:
# ### Step 8 - Start the server
```
npm run start
```
# To start the server, run:
## Configuration
# ```
# npm run start
# ```
The Lowdefy server can be configured using command-line arguments or environment variables. The command-line arguments take precedence over the environment variables.
# ## Configuration
The following command-line arguments can be specified:
# The Lowdefy server can be configured using command-line arguments or environment variables. The command-line arguments take precedence over the environment variables.
- `--build-directory`: The directory of the built Lowdefy configuration (The output of `lowdefy build`, usually found at `./.lowdefy/build` in your project repository). The default is `./.lowdefy/build`.
- `--port`: The port at which to run the server. The default is `3000`.
- `--public-directory`: The directory of the public assets to be served. The default is `./public`.
# The following command-line arguments can be specified:
# - `--build-directory`: The directory of the built Lowdefy configuration (The output of `lowdefy build`, usually found at `./.lowdefy/build` in your project repository). The default is `./.lowdefy/build`.
# - `--port`: The port at which to run the server. The default is `3000`.
# - `--public-directory`: The directory of the public assets to be served. The default is `./public`.
The following environment variables can be specified:
# The following environment variables can be specified:
- `LOWDEFY_BASE_PATH`: Set the base path to serve the Lowdefy application from. This will serve the application under `https://example.com/<base-path>`instead of `https://example.com`, and all pages under `https://example.com/<base-path>/<page-id>` instead of the default `https://example.com/<page-id>`.
- `LOWDEFY_SERVER_BUILD_DIRECTORY`: The directory of the built Lowdefy configuration (The output of `lowdefy build`, usually found at `./.lowdefy/build` in your project repository). The default is `./.lowdefy/build`.
- `LOWDEFY_SERVER_PORT`: The port at which to run the server. The default is `3000`.
- `LOWDEFY_SERVER_PUBLIC_DIRECTORY`: The directory of the public assets to be served. The default is `./public`.
# - `LOWDEFY_BASE_PATH`: Set the base path to serve the Lowdefy application from. This will serve the application under `https://example.com/<base-path>`instead of `https://example.com`, and all pages under `https://example.com/<base-path>/<page-id>` instead of the default `https://example.com/<page-id>`.
# - `LOWDEFY_SERVER_BUILD_DIRECTORY`: The directory of the built Lowdefy configuration (The output of `lowdefy build`, usually found at `./.lowdefy/build` in your project repository). The default is `./.lowdefy/build`.
# - `LOWDEFY_SERVER_PORT`: The port at which to run the server. The default is `3000`.
# - `LOWDEFY_SERVER_PUBLIC_DIRECTORY`: The directory of the public assets to be served. The default is `./public`.

2
packages/docs/head.html
View File

@ -2,5 +2,3 @@
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/docsearch.js@2.6.3/dist/cdn/docsearch.min.css"
/>
<script defer type="module" src="/public/modules/pdfMake.js"></script>
<script defer type="module" src="/public/modules/csvMake.js"></script>

13
packages/docs/introduction.yaml
View File

@ -25,11 +25,15 @@ _ref:
type: Markdown
properties:
content: |
##### TODO: This page needs to be updated.
Lowdefy simplifies creating software that helps manage internal data - think web apps, admin panels, BI dashboards, CRUD and workflow apps. Within most companies the need exists to connect to a variety of data sources and execute actions on such data. This must be done without compromising data security while respecting complex data integrity rules.
Lowdefy aims to enable companies to better control and monitor business data, by simplifying the process of creating internal tools. Lowdefy makes these tools easy to build, change and maintain, making it easier to evolve your internal tools with your business.
## Quickstart
- _ref:
path: templates/cli_command.yaml.njk
vars:
@ -98,3 +102,12 @@ _ref:
type: ScrollTo
params:
top: 0
# Message was renamed to DisplayMessage
# The following actions need to be added:
# Login
# Logout
# Fetch
# ResetValidation
# Break
# Wait

4
packages/docs/lowdefy.yaml
View File

@ -13,7 +13,7 @@
# limitations under the License.
name: '@lowdefy/docs'
lowdefy: 4.0.0-alpha.17
lowdefy: 4.0.0-alpha.22
license: Apache-2.0
cli:
@ -21,7 +21,7 @@ cli:
plugins:
- name: '@lowdefy/docs'
version: '4.0.0-alpha.10'
version: '4.0.0-alpha.22'
global:
all_icons:

213
packages/docs/menus.yaml
View File

@ -17,52 +17,52 @@
pageId: tutorial-start
properties:
title: Getting started
- id: tutorial-create-page
type: MenuLink
pageId: tutorial-create-page
properties:
title: Creating a page
- id: tutorial-add-blocks
type: MenuLink
pageId: tutorial-add-blocks
properties:
title: Adding blocks
- id: tutorial-actions-operators
type: MenuLink
pageId: tutorial-actions-operators
properties:
title: Interactive pages
- id: tutorial-requests
type: MenuLink
pageId: tutorial-requests
properties:
title: Requests
- id: tutorial-deploy
type: MenuLink
pageId: tutorial-deploy
properties:
title: Deploy to Netlify
- id: next-steps
type: MenuLink
pageId: next-steps
properties:
title: Next steps
- id: howto
type: MenuGroup
properties:
title: How To
icon: AiOutlineQuestion
links:
- id: generate-csv
type: MenuLink
pageId: generate-csv-files-from-data
properties:
title: Generate CSVs
- id: generate-pdf
type: MenuLink
pageId: generate-pdf-document-from-data
properties:
title: Generate PDFs
# - id: tutorial-create-page
# type: MenuLink
# pageId: tutorial-create-page
# properties:
# title: Creating a page
# - id: tutorial-add-blocks
# type: MenuLink
# pageId: tutorial-add-blocks
# properties:
# title: Adding blocks
# - id: tutorial-actions-operators
# type: MenuLink
# pageId: tutorial-actions-operators
# properties:
# title: Interactive pages
# - id: tutorial-requests
# type: MenuLink
# pageId: tutorial-requests
# properties:
# title: Requests
# - id: tutorial-deploy
# type: MenuLink
# pageId: tutorial-deploy
# properties:
# title: Deploy to Netlify
# - id: next-steps
# type: MenuLink
# pageId: next-steps
# properties:
# title: Next steps
# - id: howto
# type: MenuGroup
# properties:
# title: How To
# icon: AiOutlineQuestion
# links:
# - id: generate-csv
# type: MenuLink
# pageId: generate-csv-files-from-data
# properties:
# title: Generate CSVs
# - id: generate-pdf
# type: MenuLink
# pageId: generate-pdf-document-from-data
# properties:
# title: Generate PDFs
- id: concepts
type: MenuGroup
properties:
@ -144,32 +144,17 @@
pageId: custom-code
properties:
title: Custom Code
- id: custom-blocks
type: MenuLink
pageId: custom-blocks
properties:
title: Custom Blocks
- id: deployment
type: MenuGroup
properties:
title: Deployment
icon: AiOutlineCloudUpload
links:
- id: aws-lambda
type: MenuLink
pageId: aws-lambda
properties:
title: AWS Lambda
- id: docker
type: MenuLink
pageId: docker
properties:
title: Docker
- id: netlify
type: MenuLink
pageId: netlify
properties:
title: Netlify
- id: node-server
type: MenuLink
pageId: node-server
@ -186,31 +171,6 @@
pageId: users-introduction
properties:
title: Introduction
- id: openid-connect
type: MenuLink
pageId: openid-connect
properties:
title: OpenID Connect
- id: login-and-logout
type: MenuLink
pageId: login-and-logout
properties:
title: Login and Logout
- id: protected-pages
type: MenuLink
pageId: protected-pages
properties:
title: Protected pages
- id: user-object
type: MenuLink
pageId: user-object
properties:
title: User object
- id: roles
type: MenuLink
pageId: roles
properties:
title: Roles
- id: blocks_input
type: MenuGroup
@ -524,9 +484,18 @@
title: Actions
icon: AiOutlineThunderbolt
links:
- id: Break
type: MenuLink
pageId: Break
- id: CallMethod
type: MenuLink
pageId: CallMethod
- id: DisplayMessage
type: MenuLink
pageId: DisplayMessage
- id: Fetch
type: MenuLink
pageId: Fetch
- id: Link
type: MenuLink
pageId: Link
@ -536,16 +505,6 @@
- id: Logout
type: MenuLink
pageId: Logout
- id: MessageAction
type: MenuLink
pageId: MessageAction # Clash with Message block
properties:
title: Message
- id: NotificationAction
type: MenuLink
pageId: NotificationAction # Clash with Notification block
properties:
title: Notification
- id: Request
type: MenuLink
pageId: Request
@ -564,9 +523,6 @@
- id: SetState
type: MenuLink
pageId: SetState
- id: Throw
type: MenuLink
pageId: Throw
- id: Validate
type: MenuLink
pageId: Validate
@ -761,61 +717,6 @@
links:
- id: v3.23.2
type: MenuLink
url: https://docs.lowdefy.com
url: https://628bccb1bb2d810008d517c8--lowdefy-docs.netlify.app
properties:
title: v3.23.2
- id: v3.22.0
type: MenuLink
url: https://61519bcb8b8ed4412aae3057--lowdefy-docs.netlify.app
properties:
title: v3.22.0
- id: v3.21.2
type: MenuLink
url: https://612e10d3dc02710008646251--lowdefy-docs.netlify.app/introduction
properties:
title: v3.21.2
- id: v3.20.4
type: MenuLink
url: https://6121f02416ea332ef213ab7d--lowdefy-docs.netlify.app
properties:
title: v3.20.4
- id: v3.19.0
type: MenuLink
url: https://60feb65b4a8d320008674f72--lowdefy-docs.netlify.app/introduction
properties:
title: v3.19.0
- id: v3.18.1
type: MenuLink
url: https://60dc31741e179f0008eca44c--lowdefy-docs.netlify.app
properties:
title: v3.18.1
- id: v3.17.2
type: MenuLink
url: https://60c74a306748be0007f7454a--lowdefy-docs.netlify.app
properties:
title: v3.17.2
- id: v3.16.5
type: MenuLink
url: https://60b4bfc8f6822500088a1c45--lowdefy-docs.netlify.app
properties:
title: v3.16.5
- id: v3.15.0
type: MenuLink
url: https://609a6df368df720007f2cc9c--lowdefy-docs.netlify.app
properties:
title: v3.15.0
- id: v3.14.1
type: MenuLink
url: https://6089404fb5958f00070b8520--lowdefy-docs.netlify.app
properties:
title: v3.14.1
- id: v3.13.0
type: MenuLink
url: https://607952a468b9200008ad4db0--lowdefy-docs.netlify.app
properties:
title: v3.13.0
- id: v3.12.6
type: MenuLink
url: https://606c6baf132ad60007ef8f38--lowdefy-docs.netlify.app
properties:
title: v3.12.6
title: Version 3

64
packages/docs/pages.yaml
View File

@ -1,26 +1,26 @@
- _ref: introduction.yaml
- _ref: tutorial/tutorial-start.yaml
- _ref: tutorial/tutorial-create-page.yaml
- _ref: tutorial/tutorial-create-page-config.yaml
- _ref: tutorial/tutorial-add-blocks.yaml
- _ref: tutorial/tutorial-add-blocks-config.yaml
- _ref: tutorial/tutorial-actions-operators.yaml
- _ref: tutorial/tutorial-actions-operators-config.yaml
- _ref: tutorial/tutorial-requests.yaml
- _ref: tutorial/tutorial-requests-config.yaml
- _ref: tutorial/tutorial-deploy.yaml
- _ref: tutorial/next-steps.yaml
# - _ref: tutorial/tutorial-create-page.yaml
# - _ref: tutorial/tutorial-create-page-config.yaml
# - _ref: tutorial/tutorial-add-blocks.yaml
# - _ref: tutorial/tutorial-add-blocks-config.yaml
# - _ref: tutorial/tutorial-actions-operators.yaml
# - _ref: tutorial/tutorial-actions-operators-config.yaml
# - _ref: tutorial/tutorial-requests.yaml
# - _ref: tutorial/tutorial-requests-config.yaml
# - _ref: tutorial/tutorial-deploy.yaml
# - _ref: tutorial/next-steps.yaml
- _ref:
path: howto/generate-csv.yaml.njk
vars:
version:
_ref: version.yaml
- _ref:
path: howto/generate-pdf.yaml.njk
vars:
version:
_ref: version.yaml
# - _ref:
# path: howto/generate-csv.yaml.njk
# vars:
# version:
# _ref: version.yaml
# - _ref:
# path: howto/generate-pdf.yaml.njk
# vars:
# version:
# _ref: version.yaml
- _ref: concepts/overview.yaml
- _ref: concepts/cli.yaml
@ -37,19 +37,16 @@
- _ref: concepts/lists.yaml
- _ref: concepts/hosting-files.yaml
- _ref: concepts/custom-code.yaml
- _ref: concepts/custom-blocks.yaml
- _ref: deployment/aws-lambda.yaml
- _ref: deployment/docker.yaml
- _ref: deployment/netlify.yaml
- _ref: deployment/node-server.yaml
- _ref: users/users-introduction.yaml
- _ref: users/openid-connect.yaml
- _ref: users/login-and-logout.yaml
- _ref: users/protected-pages.yaml
- _ref: users/user-object.yaml
- _ref: users/roles.yaml
# - _ref: users/openid-connect.yaml
# - _ref: users/login-and-logout.yaml
# - _ref: users/protected-pages.yaml
# - _ref: users/user-object.yaml
# - _ref: users/roles.yaml
- _ref: blocks/input/AutoComplete.yaml
- _ref: blocks/input/ButtonSelector.yaml
@ -67,7 +64,7 @@
- _ref: blocks/input/PasswordInput.yaml
- _ref: blocks/input/RadioSelector.yaml
- _ref: blocks/input/RatingSlider.yaml
# - _ref: blocks/input/S3UploadButton.yaml # TODO: Add with custom plugin
# - _ref: blocks/input/S3UploadButton.yaml # TODO: Add with @lowdefy/plugin-aws
- _ref: blocks/input/Selector.yaml
- _ref: blocks/input/Switch.yaml
- _ref: blocks/input/TextArea.yaml
@ -143,20 +140,19 @@
- _ref: connections/SQLite.yaml
- _ref: connections/Stripe.yaml
- _ref: actions/Break.yaml
- _ref: actions/CallMethod.yaml
# - _ref: actions/JsAction.yaml
- _ref: actions/DisplayMessage.yaml
- _ref: actions/Fetch.yaml
- _ref: actions/Link.yaml
- _ref: actions/Login.yaml
- _ref: actions/Logout.yaml
- _ref: actions/Message.yaml
- _ref: actions/Notification.yaml
- _ref: actions/Request.yaml
- _ref: actions/Reset.yaml
- _ref: actions/ResetValidation.yaml
- _ref: actions/ScrollTo.yaml
- _ref: actions/SetGlobal.yaml
- _ref: actions/SetState.yaml
- _ref: actions/Throw.yaml
- _ref: actions/Validate.yaml
- _ref: actions/Wait.yaml
@ -171,7 +167,7 @@
- _ref: operators/_divide.yaml
- _ref: operators/_eq.yaml
- _ref: operators/_event.yaml
- _ref: operators/_format.yaml
# - _ref: operators/_format.yaml
- _ref: operators/_function.yaml
- _ref: operators/_get.yaml
- _ref: operators/_global.yaml

17
packages/docs/templates/blocks/template.yaml.njk vendored
View File

@ -18,15 +18,18 @@ requests:
- id: post_telemetry
type: AxiosHttp
connectionId: lowdefy_api_telemetry
payload:
session_id:
_global: session_id
page_id: {{ block_type }}
url_query:
_url_query: true
input:
_input: true
properties:
data:
session_id:
_global: session_id
page_id: {{ block_type }}
url_query:
_url_query: true
input:
_input: true
_payload: true
events:
onInit:

18
packages/docs/templates/blog.yaml.njk vendored
View File

@ -18,16 +18,18 @@ requests:
- id: post_telemetry
type: AxiosHttp
connectionId: lowdefy_api_telemetry
payload:
session_id:
_global: session_id
page_id:
_var: pageId
url_query:
_url_query: true
input:
_input: true
properties:
data:
session_id:
_global: session_id
page_id:
_var: pageId
url_query:
_url_query: true
input:
_input: true
_payload: true
events:
onInit:

48
packages/docs/templates/footer.yaml.njk vendored
View File

@ -187,28 +187,32 @@
- id: lowdefy_api_feedback
type: AxiosHttp
connectionId: lowdefy_api_marketing
payload:
text:
_state: feedback.text
score:
_state: feedback.score
email:
_state: feedback.email
source: docs
type: Docs feedback
page_id:
_var: pageId
properties:
data:
text:
_state: feedback.text
score:
_state: feedback.score
email:
_state: feedback.email
source: docs
type: Docs feedback
page_id:
_var: pageId
_payload: true
- id: discord_channel_feedback
type: AxiosHttp
connectionId: discord_channel
payload:
content:
_nunjucks:
template: 'Docs feedback: {{ text }}'
on:
_state: feedback
properties:
data:
content:
_nunjucks:
template: 'Docs feedback: {{ text }}'
on:
_state: feedback
_payload: true
layout:
size: auto
properties:
@ -422,14 +426,16 @@
- id: lowdefy_api_subscribe
type: AxiosHttp
connectionId: lowdefy_api_marketing
payload:
type: Newsletter subscription
email:
_state: footer_cta_input
source: docs
page_id:
_var: pageId
properties:
data:
type: Newsletter subscription
email:
_state: footer_cta_input
source: docs
page_id:
_var: pageId
_payload: true
- id: discord_channel_subscribe
type: AxiosHttp
connectionId: discord_channel

19
packages/docs/templates/general.yaml.njk vendored
View File

@ -18,16 +18,18 @@ requests:
- id: post_telemetry
type: AxiosHttp
connectionId: lowdefy_api_telemetry
payload:
session_id:
_global: session_id
page_id:
_var: pageId
url_query:
_url_query: true
input:
_input: true
properties:
data:
session_id:
_global: session_id
page_id:
_var: pageId
url_query:
_url_query: true
input:
_input: true
_payload: true
events:
onInit:
@ -54,6 +56,7 @@ events:
error: false
params: post_telemetry
properties:
title: {{ pageTitle }}
header:

445
packages/docs/tutorial/tutorial-start.yaml
View File

@ -22,261 +22,266 @@ _ref:
prefetchPages:
- tutorial-create-page
content:
- id: tutorial_video
type: DangerousMarkdown
properties:
DOMPurifyOptions:
ADD_TAGS:
- iframe
ADD_ATTR:
- allowfullscreen
- allow
- frameborder
content: |
<iframe
width="800"
height="470"
src="https://www.youtube.com/embed/Cd4Xxxisykg" frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen>
</iframe>
- id: body_start
- id: body_todo
type: MarkdownWithCode
properties:
content: |
In this tutorial, we will be creating a simple ticketing app, that allows users to file new tickets and see a list of outstanding tickets. The app will write the ticket data to Google Sheets, and we will deploy the app using [Netlify](https://www.netlify.com).
##### TODO: The tutorial will be revised for Lowdefy v4.
### Requirements
# - id: tutorial_video
# type: DangerousMarkdown
# properties:
# DOMPurifyOptions:
# ADD_TAGS:
# - iframe
# ADD_ATTR:
# - allowfullscreen
# - allow
# - frameborder
# content: |
# <iframe
# width="800"
# height="470"
# src="https://www.youtube.com/embed/Cd4Xxxisykg" frameborder="0"
# allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen>
# </iframe>
# - id: body_start
# type: MarkdownWithCode
# properties:
# content: |
# In this tutorial, we will be creating a simple ticketing app, that allows users to file new tickets and see a list of outstanding tickets. The app will write the ticket data to Google Sheets, and we will deploy the app using [Netlify](https://www.netlify.com).
The Lowdefy CLI (Command Line Interface) is needed to run the development server. To run the Lowdefy CLI you need to install Node.js at version 12 or greater. If you don't have it installed, download Node.js from https://nodejs.org/en/download/, and follow the installation steps for your computer. All of the default settings given by the installer are fine for what we need. You will also need a text editor to modify the Lowdefy configuration files.
# ### Requirements
#### Step 1.1 - Create a project directory
# The Lowdefy CLI (Command Line Interface) is needed to run the development server. To run the Lowdefy CLI you need to install Node.js at version 12 or greater. If you don't have it installed, download Node.js from https://nodejs.org/en/download/, and follow the installation steps for your computer. All of the default settings given by the installer are fine for what we need. You will also need a text editor to modify the Lowdefy configuration files.
Create a directory (folder) on your computer where you would like to create the configuration files for your project. We will be referring to this directory as the project directory
# #### Step 1.1 - Create a project directory
#### Step 1.2 - Open a command line interface
# Create a directory (folder) on your computer where you would like to create the configuration files for your project. We will be referring to this directory as the project directory
Open your computer's command line interface (Windows CMD, Terminal on MacOS), and change directory (`cd`) to the project directory.
# #### Step 1.2 - Open a command line interface
#### Step 1.3 - Initialize an app
# Open your computer's command line interface (Windows CMD, Terminal on MacOS), and change directory (`cd`) to the project directory.
Use the Lowdefy CLI to initialize your project.
# #### Step 1.3 - Initialize an app
Run the following in your terminal:
# Use the Lowdefy CLI to initialize your project.
- _ref:
path: templates/cli_command.yaml.njk
vars:
id: init
command: 'npx lowdefy@latest init'
# Run the following in your terminal:
- id: body_init
type: MarkdownWithCode
properties:
content: |
This will create two files in your current working directory. The first file, called `lowdefy.yaml` is the starting point of your app's configuration. The second, called `.gitignore`, is a hidden file that tells `git`, a version control tool, not to version or upload some specific files.
# - _ref:
# path: templates/cli_command.yaml.njk
# vars:
# id: init
# command: 'npx lowdefy@latest init'
> We recommend using [`npx`](https://docs.npmjs.com/cli/v7/commands/npx) to run the Lowdefy CLI, since this ensures your are always running the latest version. You can also install the CLI globally or locally using `npm install lowdefy`
# - id: body_init
# type: MarkdownWithCode
# properties:
# content: |
# This will create two files in your current working directory. The first file, called `lowdefy.yaml` is the starting point of your app's configuration. The second, called `.gitignore`, is a hidden file that tells `git`, a version control tool, not to version or upload some specific files.
- id: info_windows_paste
type: Alert
properties:
type: info
icon: AiFillInfoCircle
description: To paste into the Windows Command Prompt, you can right-click and select paste.
# > We recommend using [`npx`](https://docs.npmjs.com/cli/v7/commands/npx) to run the Lowdefy CLI, since this ensures your are always running the latest version. You can also install the CLI globally or locally using `npm install lowdefy`
- id: error_already_exists
type: Alert
properties:
type: error
icon: AiOutlineFire
message: A "lowdefy.yaml" file already exists
description: If you get a 'A "lowdefy.yaml" file already exists' error, delete the "lowdefy.yaml" file in your current working directory or run the command in a new directory.
# - id: info_windows_paste
# type: Alert
# properties:
# type: info
# icon: AiFillInfoCircle
# description: To paste into the Windows Command Prompt, you can right-click and select paste.
- id: body_start_dev
type: MarkdownWithCode
properties:
content: |
#### Step 1.4 - Start the development server.
# - id: error_already_exists
# type: Alert
# properties:
# type: error
# icon: AiOutlineFire
# message: A "lowdefy.yaml" file already exists
# description: If you get a 'A "lowdefy.yaml" file already exists' error, delete the "lowdefy.yaml" file in your current working directory or run the command in a new directory.
Run:
# - id: body_start_dev
# type: MarkdownWithCode
# properties:
# content: |
# #### Step 1.4 - Start the development server.
- _ref:
path: templates/cli_command.yaml.njk
vars:
id: dev
command: 'npx lowdefy@latest dev'
# Run:
- id: body_open_browser
type: MarkdownWithCode
properties:
content: |
Your browser should open on http://localhost:3000, and you should see the following:
# - _ref:
# path: templates/cli_command.yaml.njk
# vars:
# id: dev
# command: 'npx lowdefy@latest dev'
- id: example1
type: PageHeaderMenu
properties:
style:
minHeight: 300px
menu:
links:
- id: welcome
type: MenuLink
properties:
title: welcome
# - id: body_open_browser
# type: MarkdownWithCode
# properties:
# content: |
# Your browser should open on http://localhost:3000, and you should see the following:
blocks:
- id: content_card
type: Card
areas:
content:
blocks:
- id: content
type: Result
properties:
title: Welcome to your Lowdefy app
subTitle: We are excited to see what you are going to build
status: success
icon:
name: AiOutlineHeart
color: '#f00'
areas:
extra:
blocks:
- id: docs_button
type: Button
properties:
size: large
title: Let's build something
events:
onClick:
- id: link_to_docs
type: Link
params:
url: https://docs.lowdefy.com
newTab: true
footer:
blocks:
- id: footer
type: Paragraph
properties:
type: secondary
content: |
Made by a Lowdefy 🤖
# - id: example1
# type: PageHeaderMenu
# properties:
# style:
# minHeight: 300px
# menu:
# links:
# - id: welcome
# type: MenuLink
# properties:
# title: welcome
- id: error_could_not_find
type: Alert
properties:
type: error
icon: AiOutlineFire
message: Could not find "lowdefy.yaml"
description: If you get a 'Could not find "lowdefy.yaml"' error, make sure your current working directory contains the "lowdefy.yaml" file. You can verify this by running the "dir" (Windows) or "ls" (MacOS) command.
# blocks:
# - id: content_card
# type: Card
# areas:
# content:
# blocks:
# - id: content
# type: Result
# properties:
# title: Welcome to your Lowdefy app
# subTitle: We are excited to see what you are going to build
# status: success
# icon:
# name: AiOutlineHeart
# color: '#f00'
# areas:
# extra:
# blocks:
# - id: docs_button
# type: Button
# properties:
# size: large
# title: Let's build something
# events:
# onClick:
# - id: link_to_docs
# type: Link
# params:
# url: https://docs.lowdefy.com
# newTab: true
# footer:
# blocks:
# - id: footer
# type: Paragraph
# properties:
# type: secondary
# content: |
# Made by a Lowdefy 🤖
- id: body_edit
type: MarkdownWithCode
properties:
content: |
#### Step 1.5 - Open the configuration file
# - id: error_could_not_find
# type: Alert
# properties:
# type: error
# icon: AiOutlineFire
# message: Could not find "lowdefy.yaml"
# description: If you get a 'Could not find "lowdefy.yaml"' error, make sure your current working directory contains the "lowdefy.yaml" file. You can verify this by running the "dir" (Windows) or "ls" (MacOS) command.
Open the `lowdefy.yaml` file using a text editor like [VS Code](https://code.visualstudio.com/download). The content of the file should look like this:
# - id: body_edit
# type: MarkdownWithCode
# properties:
# content: |
# #### Step 1.5 - Open the configuration file
```yaml
lowdefy: 3.23.2
name: Lowdefy starter
# Open the `lowdefy.yaml` file using a text editor like [VS Code](https://code.visualstudio.com/download). The content of the file should look like this:
pages:
- id: welcome
type: PageHeaderMenu
properties:
title: Welcome
areas:
content:
justify: center
blocks:
- id: content_card
type: Card
style:
maxWidth: 800
blocks:
- id: content
type: Result
properties:
title: Welcome to your Lowdefy app
subTitle: We are excited to see what you are going to build
icon:
name: AiOutlineHeart
color: '#f00'
areas:
extra:
blocks:
- id: docs_button
type: Button
properties:
size: large
title: Let's build something
color: '#1890ff'
events:
onClick:
- id: link_to_docs
type: Link
params:
url: https://docs.lowdefy.com
newWindow: true
footer:
blocks:
- id: footer
type: Paragraph
properties:
type: secondary
content: |
Made by a Lowdefy 🤖
```
# ```yaml
# lowdefy: 3.23.2
# name: Lowdefy starter
This configuration completely describes the app you are running.
# pages:
# - id: welcome
# type: PageHeaderMenu
# properties:
# title: Welcome
# areas:
# content:
# justify: center
# blocks:
# - id: content_card
# type: Card
# style:
# maxWidth: 800
# blocks:
# - id: content
# type: Result
# properties:
# title: Welcome to your Lowdefy app
# subTitle: We are excited to see what you are going to build
# icon:
# name: AiOutlineHeart
# color: '#f00'
# areas:
# extra:
# blocks:
# - id: docs_button
# type: Button
# properties:
# size: large
# title: Let's build something
# color: '#1890ff'
# events:
# onClick:
# - id: link_to_docs
# type: Link
# params:
# url: https://docs.lowdefy.com
# newWindow: true
# footer:
# blocks:
# - id: footer
# type: Paragraph
# properties:
# type: secondary
# content: |
# Made by a Lowdefy 🤖
# ```
# This configuration completely describes the app you are running.
#### Step 1.6 - Make some changes
# #### Step 1.6 - Make some changes
Change some of the text in the app. Change the text `Welcome to your Lowdefy app` to `Hello __YOUR_NAME_HERE__` (filling in your own name). Save the file and browser should automatically refresh, and you should see your changes.
# Change some of the text in the app. Change the text `Welcome to your Lowdefy app` to `Hello __YOUR_NAME_HERE__` (filling in your own name). Save the file and browser should automatically refresh, and you should see your changes.
### YAML Files
# ### YAML Files
Lowdefy apps are written using YAML files. YAML files are useful for storing structured data, like the configuration of all of the elements of your app. YAML files focus on being easily readable by humans, this means they don't use lots of syntactic elements like brackets that make it difficult for humans to read, but instead use __indentation to indicate structure__. While this does make the file easier to read, this means care has to be taken that the data structure is as you intended. If you don't have any experience using YAML, this video is a good introduction.
- id: body_yaml_vid
type: DangerousMarkdown
properties:
DOMPurifyOptions:
ADD_TAGS:
- iframe
ADD_ATTR:
- allowfullscreen
- allow
- frameborder
content: |
<iframe
id="ytplayer-yaml-video"
type="text/html"
width="800"
height="470"
src="https://www.youtube.com/embed/cdLNKUoMc6c?origin=https://docs.lowdefy.com"
allowfullscreen="true"
frameborder="0">
</iframe>
- id: body_what_happened
type: Markdown
properties:
content: |
### What happened
# Lowdefy apps are written using YAML files. YAML files are useful for storing structured data, like the configuration of all of the elements of your app. YAML files focus on being easily readable by humans, this means they don't use lots of syntactic elements like brackets that make it difficult for humans to read, but instead use __indentation to indicate structure__. While this does make the file easier to read, this means care has to be taken that the data structure is as you intended. If you don't have any experience using YAML, this video is a good introduction.
# - id: body_yaml_vid
# type: DangerousMarkdown
# properties:
# DOMPurifyOptions:
# ADD_TAGS:
# - iframe
# ADD_ATTR:
# - allowfullscreen
# - allow
# - frameborder
# content: |
# <iframe
# id="ytplayer-yaml-video"
# type="text/html"
# width="800"
# height="470"
# src="https://www.youtube.com/embed/cdLNKUoMc6c?origin=https://docs.lowdefy.com"
# allowfullscreen="true"
# frameborder="0">
# </iframe>
# - id: body_what_happened
# type: Markdown
# properties:
# content: |
# ### What happened
The Lowdefy CLI helps you develop a Lowdefy app.
# The Lowdefy CLI helps you develop a Lowdefy app.
We used the `npx lowdefy@latest init` command to initialize a new project. This created all the essential files.
# We used the `npx lowdefy@latest init` command to initialize a new project. This created all the essential files.
We also used the `npx lowdefy@latest dev` command to start a development server. The development server runs a Lowdefy app locally on your computer, which can be accessed at http://localhost:3000. The development server watches your configuration files, and if any of them changes it "builds" (compiles the configuration together for the server to serve) the configuration again and refreshes the browser to show the changes.
# We also used the `npx lowdefy@latest dev` command to start a development server. The development server runs a Lowdefy app locally on your computer, which can be accessed at http://localhost:3000. The development server watches your configuration files, and if any of them changes it "builds" (compiles the configuration together for the server to serve) the configuration again and refreshes the browser to show the changes.
- _ref:
path: templates/navigation_buttons.yaml
vars:
previous_page_title: Introduction
previous_page_id: introduction
next_page_title: Creating a page
next_page_id: tutorial-create-page
# - _ref:
# path: templates/navigation_buttons.yaml
# vars:
# previous_page_title: Introduction
# previous_page_id: introduction
# next_page_title: Creating a page
# next_page_id: tutorial-create-page

100
packages/docs/users/users-introduction.yaml
View File

@ -24,57 +24,59 @@ _ref:
type: Markdown
properties:
content: |
To add user authentication and authorization to a Lowdefy app, you need to do the following:
- Configure an OpenID Connect provider
- Configure which pages should be public and protected (only available to logged in users).
- Add the `Login` and `Logout` actions to your app, to allow users to log in and out.
##### TODO: This page needs to be updated.
Optionally, you can also:
- Use role based authorization to make certain pages available only to users with the correct roles.
# To add user authentication and authorization to a Lowdefy app, you need to do the following:
# - Configure an OpenID Connect provider
# - Configure which pages should be public and protected (only available to logged in users).
# - Add the `Login` and `Logout` actions to your app, to allow users to log in and out.
An example app implementing OpenID Connect can be found [here](https://github.com/lowdefy/lowdefy-example-openid-connect).
# Optionally, you can also:
# - Use role based authorization to make certain pages available only to users with the correct roles.
- id: jwt_session_warning
type: Alert
properties:
type: warning
icon: AiFillWarning
message: Stateful JSON Web Tokens are used for authentication
description: Lowdefy uses stateful JSON Web Tokens for user authentication, since the Lowdefy server is stateless and does not maintain a database of user sessions. This means that once a token is issued, it is valid until the token expires. Any changes to the user's access will only reflect after the token has expired, and the user obtains (or fails to obtain) a new token from the OpenID Connect provider. We recommend making sure tokens have a relatively short expiry time (the default is 4 hours), and evaluating if the security provided by this system is appropriate for your use case.
# An example app implementing OpenID Connect can be found [here](https://github.com/lowdefy/lowdefy-example-openid-connect).
- id: auth_config
type: MarkdownWithCode
properties:
content: |
Most authorization and authentication settings are configured in the `config.auth` object in the Lowdefy configuration. The following config can be set:
```yaml
lowdefy: 3.23.2
config:
auth:
openId:
# The url the user should be redirected to after logout.
logoutRedirectUri: [string]
# Field in the user idToken that contains the roles array.
rolesField: [string]
# The OpenID Connect scope to request. The default is 'openid profile email'.
scope: [string]
jwt:
# The length of time a user token should be valid.
expiresIn: [string | number]
pages:
# Either set all pages as protected, or list specific protected pages.
protected: [boolean | string[]]
# Either set all pages as public, or list specific public pages.
public: [boolean | string[]]
roles:
# Restrict pages to only users with a certain role.
{roleName}: string[]
```
# - id: jwt_session_warning
# type: Alert
# properties:
# type: warning
# icon: AiFillWarning
# message: Stateful JSON Web Tokens are used for authentication
# description: Lowdefy uses stateful JSON Web Tokens for user authentication, since the Lowdefy server is stateless and does not maintain a database of user sessions. This means that once a token is issued, it is valid until the token expires. Any changes to the user's access will only reflect after the token has expired, and the user obtains (or fails to obtain) a new token from the OpenID Connect provider. We recommend making sure tokens have a relatively short expiry time (the default is 4 hours), and evaluating if the security provided by this system is appropriate for your use case.
- _ref:
path: templates/navigation_buttons.yaml
vars:
previous_page_title: Overview
previous_page_id: overview
next_page_title: OpenID Connect
next_page_id: openid-connect
# - id: auth_config
# type: MarkdownWithCode
# properties:
# content: |
# Most authorization and authentication settings are configured in the `config.auth` object in the Lowdefy configuration. The following config can be set:
# ```yaml
# lowdefy: 3.23.2
# config:
# auth:
# openId:
# # The url the user should be redirected to after logout.
# logoutRedirectUri: [string]
# # Field in the user idToken that contains the roles array.
# rolesField: [string]
# # The OpenID Connect scope to request. The default is 'openid profile email'.
# scope: [string]
# jwt:
# # The length of time a user token should be valid.
# expiresIn: [string | number]
# pages:
# # Either set all pages as protected, or list specific protected pages.
# protected: [boolean | string[]]
# # Either set all pages as public, or list specific public pages.
# public: [boolean | string[]]
# roles:
# # Restrict pages to only users with a certain role.
# {roleName}: string[]
# ```
# - _ref:
# path: templates/navigation_buttons.yaml
# vars:
# previous_page_title: Overview
# previous_page_id: overview
# next_page_title: OpenID Connect
# next_page_id: openid-connect