mirror/lowdefy
2
0
Fork 0
mirror of https://github.com/lowdefy/lowdefy.git synced 2025-04-06 15:30:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): Updates to custom code docs.

Browse Source
This commit is contained in:
SamTolmay 2021-05-25 14:51:51 +02:00
parent d47c31f0b3
commit a4be53077a
4 changed files with 38 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -28,7 +28,7 @@ _ref:
}): 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 JavaScript](/custom-javascript) for more details on how to register a new JavaScript action.
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 action in the event action list.
@ -40,7 +40,7 @@ _ref:
state: object,
urlQuery: object,
input: object,
},
},
...args?: any[]): any
```
params: |
@ -86,7 +86,7 @@ _ref:
params:
name: setIntercomUser
blocks:
...
# ...
```
##### Highlight search term returned by [MongoDB Search Highlight](https://docs.atlas.mongodb.com/reference/atlas-search/highlighting/):
@ -177,7 +177,7 @@ _ref:
- $addFields:
score:
$meta: searchScore
highlights:
highlights:
$meta: searchHighlights
blocks:
- id: search.input
@ -199,7 +199,7 @@ _ref:
- id: set_state # set the response of the apply_highlight action to state
type: SetState
params:
found_products:
found_products:
_actions: apply_highlight.response
- id: product_results
type: Html
@ -213,7 +213,7 @@ _ref:
{% endfor %}
</ul>
on:
found_products:
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:

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

@ -24,7 +24,7 @@ _ref:
type: Alert
properties:
message: |
SECURITY WARNING: Blocks executes JavaScript inside your Lowdefy app. Insecure code can expose your app or data. Make sure that you only load blocks from trusted a source.
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
@ -35,9 +35,9 @@ _ref:
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 fast and can be used inside Lowdefy apps with ease.
- 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 which a easy application interface.
- 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
@ -160,7 +160,7 @@ _ref:
## 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 URL is pointing to where your block is hosted.
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.
@ -168,7 +168,7 @@ _ref:
- _ref:
path: templates/navigation_buttons.yaml
vars:
previous_page_title: Lists
previous_page_id: lists
previous_page_title: Custom Code
previous_page_id: custom-code
next_page_title: User authentication
next_page_id: users-introduction

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

@ -30,9 +30,9 @@ _ref:
type: MarkdownWithCode
properties:
content: |
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.
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 is 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.
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.
> __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,9 +72,9 @@ _ref:
## Hosting static files
A Lowdefy app provides a convenient method to host __public__ files under the `/public/*` app route. Add content to be hosted publicly by creating a folder named `public` in the root of a Lowdefy project folder, next to the `lowdefy.yaml` file. Place the public content in this folder to host this content with your app.
A Lowdefy app provides a convenient method to host __public__ files under the `/public/*` app route. Add content to be hosted publicly by creating a folder named `public` in the root of a Lowdefy project folder, next to the `lowdefy.yaml` file. Place the public content in this folder to host this content with your app.
All content in this folder will be publicly accessible at `{{ APP_URL }}/public/{{ FILE_PATH_NAME }}`. For example, the logo at the top of this page is hosted at [`https://docs.lowdefy.com/public/logo-light-theme.png`](http://localhost:3000/public/logo-light-theme.png). Sub-folders inside the public folder is supported.
All content in this folder will be publicly accessible at `{{ APP_URL }}/public/{{ FILE_PATH_NAME }}`. For example, the logo at the top of this page is hosted at [`https://docs.lowdefy.com/public/logo-light-theme.png`](http://localhost:3000/public/logo-light-theme.png). Sub-folders inside the public folder are supported.
By default, the `public` folder of a Lowdefy app will serve some files which most apps need:
- `apple-touch-icon.png`: A 180x180px png image file to be used as the apple PWA icon.
@ -91,13 +91,13 @@ _ref:
## Loading and registering a [`JsAction`](/JsAction)
In order for the Lowdefy app engine to execute a custom JavaScript [action](/events-and-actions), the JavaScript code for the action must be loaded onto the page and registered using the `registerJsAction` method available on the browser [`window`](https://developer.mozilla.org/en-US/docs/Web/API/window) object by calling `window.lowdefy.registerJsAction(name: string, action: function)`.
In order for the Lowdefy app engine to execute a custom JavaScript [action](/events-and-actions), the JavaScript code for the action must be loaded onto the page and registered using the `registerJsAction` method available on the browser [`window`](https://developer.mozilla.org/en-US/docs/Web/API/window) object by calling `window.lowdefy.registerJsAction(name: string, action: function)`.
The `JsAction` allows the use of async functions.
###### 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).
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
@ -108,7 +108,7 @@ _ref:
return todos.slice(skip, skip + numItems);
}
// Register the JsAction for the Lowdefy app to use.
window.lowdefy.registerJsAction('fetchTodos', fetchTodos);
window.lowdefy.registerJsAction('fetchTodos', fetchTodos);
```
2) Import the JavaScript as a module into the page:
@ -124,7 +124,7 @@ _ref:
lowdefy: 3.15.0
app:
html:
appendHead:
appendHead:
_ref: header_modules.html # Load the custom HTML into the header.
pages:
- id: todos
@ -141,21 +141,21 @@ _ref:
- id: set_todos
type: SetState
params:
todos:
todos:
# Set the response of the get_todos action to state.
_actions: get_todos.response
_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 [operators](/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)`.
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.
###### 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.
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
@ -164,7 +164,7 @@ _ref:
return [ ...new Set(items) ];
}
// Register the removeDuplicates function as a _js.deduplicate operator.
window.lowdefy.registerJsOperator('deduplicate', removeDuplicates);
window.lowdefy.registerJsOperator('deduplicate', removeDuplicates);
```
2) Import the JavaScript as a module into the page:
@ -180,7 +180,7 @@ _ref:
lowdefy: 3.15.0
app:
html:
appendHead:
appendHead:
_ref: header.html # Load the custom HTML into the header.
pages:
- id: some_names
@ -191,8 +191,8 @@ _ref:
properties:
title: Select your new friend
options:
# use the removeDuplicates function and pass a list of names as a function argument
_js.deduplicate:
# use the removeDuplicates function and pass a list of names as a function argument
_js.deduplicate:
- - Anne
- Sam
- Joe

18
packages/docs/operators/_js.yaml
View File

@ -27,16 +27,18 @@ _ref:
(args: any[]): any
```
description: |
The `_js` operator executes a synchronous JavaScript function when the operator is evaluated. To use the `_js` function the following is needed:
The `_js` operator executes a JavaScript function when the operator is evaluated. If used in a block, this function is called every time the Lowdefy engine checks if any block on the page should be updated. This function must be synchronous, and it is highly recommended that it is a pure function (it always returns the same result for the same input, and does not have side effects). Since it is called often it should also execute quickly, a slow operator will slow down the entire app. The [`JsAction`](/JsAction) action can be used to execute asynchronous code when an event is triggered.
- Load the custom JavaScript into the app `head` tag. See the [Custom JavaScript](/custom-javascript) section for more details.
To use the `_js` operator the following is needed:
- Load the custom JavaScript into the app `head` tag. See the [Custom Code](/custom-code) section for more details.
- In the custom JavaScript, pass the JavaScript operator function to the app using the `window.lowdefy.registerJsOperator(name: string, operatorFunction: function)` method.
- A list of arguments can be passed to the JavaScript function which will be spread as function parameters.
- The returned value of the custom JavaScript function will be the operator result.
-----------
> DEPRECATION WARNING: The QuickJS JavaScript operators are depreciated and will be removed in the next version. Instead native browser functions can now be loaded at build time by registering the operator function with `window.lowdefy.registerJsOperator(name: string, operatorFunction: function)`. See the [Custom JavaScript](/custom-javaScript) section for details.
> DEPRECATION WARNING: The QuickJS JavaScript operators are depreciated and will be removed in the next version. Instead native browser functions can now be loaded at build time by registering the operator function with `window.lowdefy.registerJsOperator(name: string, operatorFunction: function)`. See the [Custom Code](/custom-code) section for details.
For depreciated `evaluate`, and `function`, the following applies to the JavaScript function definitions:
- The `code` operator argument requires a function definition.
@ -55,9 +57,9 @@ _ref:
(args?: any[]): any
```
description: |
The `_js.{{ method_name }}` method evaluates the JavaScript function as registered using `window.lowdefy.registerJsOperator(method_name: string, method: function)`. When passing a list of arguments to the JavaScript function, then list of arguments will be spread as function parameters.
The `_js.{{ method_name }}` method evaluates the JavaScript function as registered using `window.lowdefy.registerJsOperator(method_name: string, method: function)`. When passing a list of arguments to the JavaScript function, then list of arguments will be spread as function parameters.
The loaded JavaScript function must be synchronous. See the [Custom JavaScript](/custom-javascript) section for more detail on how to load custom JavaScript operators.
The loaded JavaScript function must be a synchronous pure function. See the [Custom JavaScript](/custom-javascript) section for more detail on how to load custom JavaScript operators.
examples: |
##### A custom JavaScript operator to calculate primes:
```yaml
@ -75,7 +77,7 @@ _ref:
[...Array(n-2).keys()].map(i=>i+2).reduce((acc,x)=> acc && n % x !== 0, true));
}
// Register the JavaScript operator function.
window.lowdefy.registerJsOperator('makePrimes', makePrimes);
window.lowdefy.registerJsOperator('makePrimes', makePrimes);
</script>
pages:
- id: home
@ -134,7 +136,7 @@ _ref:
lowdefy: '3.15.0'
app:
html:
appendHead:
appendHead:
_ref: imports.html # Loading html content into the application head tag.
pages:
- id: home
@ -180,7 +182,7 @@ _ref:
textBorderColor: '#fff'
textBorderWidth: 2
formatter:
_js.getLabel: # Use the getLabel function
_js.getLabel: # Use the getLabel function
- 'radial'
- 'tangential'
- 'other'