@lowdefy/docs 4.0.0-alpha.7 → 4.0.0-alpha.8

package/concepts/lists.yaml

@@ -1,162 +0,0 @@
-_ref:
-  path: templates/general.yaml.njk
-  vars:
-    pageId: lists
-    pageTitle: Lists
-    section: Concepts
-    filePath: concepts/lists.yaml
-    content:
-      - id: md1
-        type: MarkdownWithCode
-        properties:
-          content: |
-            List category blocks render multiple [`content areas`](/layout), based on data in the [`state`](/context-and-state) object.
-
-            Since the content area might contain input blocks, the block has an array value in state, with it's `block id` as key. For each item in the array, an content area (or set of content areas is rendered). Multiple list blocks can be nested.
-
-            ### List indices and block ids
-
-            If a block is to be rendered in an list's content area, the block id should contain a list index placeholder (specified with the `$` symbol) for each list it is a part of. These placeholders will be populated with the blocks `list indices`. The `list indices` are a array of integers, indicating at which position in the list the block is, for each level of list blocks (zero indexed). The block id should be in valid dot-notation once the placeholders have been substituted.
-
-            This can be made more clear with a example. Suppose we have a list block with id `contacts`. Inside this list we have a text input block for the contact name. We would like our state to look like:
-            ```yaml
-            contacts:
-              - name: Name 1
-              - name: Name 2
-            ```
-
-            The id for the text input block should be `contacts.$.name`. Each text input block will be given an indexed id based on it's position in the contacts list (`contacts.0.name`, `contacts.1.name`, etc.).
-
-            Suppose we also want to add a emails array for each contact. To do this, we can add another list block in the `contacts` array, and add a text input inside the emails array. If we want the emails to be a array of strings, i.e. our `state` should look like:
-
-            ```yaml
-            contacts:
-              - name: Name 1
-                emails:
-                  - email1@example.com
-                  - email2@example.com
-              - name: Name 2
-                emails: []
-            ```
-
-            our config should look like:
-            ```yaml
-            id: contacts
-            type: ControlledList
-            properties:
-              # ...
-            blocks:
-              - id: contacts.$.name
-                type: TextInput
-                properties:
-                  # ...
-              - id: contacts.$.emails
-                type: ControlledList
-                properties:
-                  # ...
-                blocks:
-                  - id: contacts.$.emails.$
-                    type: TextInput
-                    properties:
-                      # ...
-            ```
-
-            Note that the id of the emails list block is `contacts.$.emails` and that it has one `$` placeholder since it is inside the `contacts` list, and the id of the email text input is `contacts.$.emails.$`, which has two `$` placeholders since it is in both the `contacts` and `contacts.$.emails` lists.
-
-            The ids of the `contacts.$.emails.$` text input blocks will look like `contacts.0.emails.3` or `contacts.2.emails.1`, and this will result in the `state` where the emails on a contact are an array of strings.
-
-            ### List indices in operators
-
-            List indices are also supported in "getter" operators like `_state`. If the operator is given a key that contains `$` placeholders, and the operator is called from a block with list indices, the placeholders will be populated with the blocks list indices. These indices are populated on `actions` called by the block, and are even populated in `connections` and `requests` if the block that triggered the `Request` action has list indices. This can be used to get values from the `state` array the block is a part of, or even values from another array at the same index.
-
-            ### List block methods
-
-            List blocks can provide methods to change their values. These are
-
-            #### `pushItem`
-            Add an item at the end of the list.
-
-            #### `unshiftItem`
-            Add an item at the start of the list.
-
-            #### `removeItem`
-            Remove an item at the specified index.
-
-            #### `moveItemDown`
-            Move the item at the specified index one position to the start of the list. If the item is at the start if the list, the item remains at position `0`.
-
-            #### `moveItemUp`
-            Move the item at the specified index one position to the end of the list. If the item is at the end if the list, the item remains at it's position.
-
-            #### Example
-            ```yaml
-            id: page
-            type: PageHeaderMenu
-            blocks:
-              - id: add_item_at_start
-                type: Button
-                events:
-                  onClick:
-                    - id: add_item_at_start
-                      type: CallMethod
-                      params:
-                        blockId: list
-                        method: unshiftItem
-              - id: add_item_at_end
-                type: Button
-                events:
-                  onClick:
-                    - id: add_item_at_end
-                      type: CallMethod
-                      params:
-                        blockId: list
-                        method: pushItem
-              - id: list
-                type: List
-                blocks:
-                  - id: list.$.move_item_down
-                    type: Button
-                    events:
-                      onClick:
-                        - id: move_item_down
-                          type: CallMethod
-                          params:
-                            blockId: list
-                            method: moveItemDown
-                            args:
-                              - _index: 0 # Get the first index in the indices array
-                  - id: list.$.move_item_up
-                    type: Button
-                    events:
-                      onClick:
-                        - id: move_item_up
-                          type: CallMethod
-                          params:
-                            blockId: list
-                            method: moveItemUp
-                            args:
-                              - _index: 0
-                  - id: list.$.remove_item
-                    type: Button
-                    events:
-                      onClick:
-                        - id: remove_item
-                          type: CallMethod
-                          params:
-                            blockId: list
-                            method: removeItem
-                            args:
-                              - _index: 0
-            ```
-
-            ### Lists and state
-
-            List blocks create a content area for each item in `state`. If `state` is updated, the list block will also update, creating or destroying content areas as necessary. Thus list blocks can also be manipulated by setting `state` directly using the [`SetState`](/SetState) operator.
-
-      - _ref:
-          path: templates/navigation_buttons.yaml
-          vars:
-            previous_page_title: Secrets
-            previous_page_id: secrets
-            next_page_title: Hosting Files
-            next_page_id: hosting-files

package/concepts/lowdefy-schema.yaml

@@ -1,245 +0,0 @@
-# Copyright 2020-2021 Lowdefy, Inc
-
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-
-#     http://www.apache.org/licenses/LICENSE-2.0
-
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-_ref:
-  path: templates/general.yaml.njk
-  vars:
-    pageId: lowdefy-schema
-    pageTitle: Lowdefy App Schema
-    section: Concepts
-    filePath: concepts/lowdefy-schema.yaml
-    content:
-      - id: md1
-        type: MarkdownWithCode
-        properties:
-          content: |
-            A Lowdefy app is written as YAML files, which are combined together using the `_ref` operator when the app is built, into a configuration object that describes the entire app. This object has different sections that describes different parts of the app.
-
-            The root schema for a Lowdefy app is:
-            - `lowdefy: string`: __Required__ - The Lowdefy version number the app uses. This is required and cannot be a reference to another file.
-            - `name: string`: A name for the application.
-            - `licence: string`: A [SPDX licence ID](https://spdx.org/licenses/). You can use this to indicate the project's  licence if you are licencing your project under a specific software licence. If you wish to indicate to others that you do not grant the right to use your project, you can optionally use `UNLICENSED` for this field. How you share your Lowdefy config is up to you.
-            - `cli: object`: An object with configuration for the CLI.
-            - `config: object`: An object with app configuration like the home page pageId.
-            - `global: object`: A data object that can be accessed anywhere in the app using the [`_global`](/_global) operator.
-            - `connections: object[]`: An array of [`connection`](/connections-and-requests) objects.
-            - `types: object`: An object to customize and add block types.
-            - `menus: object[]`: An array of menu objects.
-            - `pages: object[]`: An array of page objects.
-
-            # Config
-
-            The config object has the following properties:
-
-            - `basePath: string`: Set the base path to serve the Lowdefy application from. This will route all pages under `https://example.com/<base-path>/<page-id>` instead of the default `https://example.com/<page-id>`. The basePath value must start with "/".
-            - `homePageId: string`: The pageId of the page that should be loaded when a user loads the app without a pageId in the url route. This is the page that is loaded when you navigate to `yourdomain.com`.
-            - `experimental_initPageId: string`: The pageId of the page that should be loaded when app is initialized. User is then redirected to requeted page. You can use onInit/onInitAsync/onEnter/onEnterAsync events to fetch and prepare global variables for other parts of the app.
-
-      - id: alert1
-        type: Alert
-        properties:
-          type: warning
-          showIcon: false
-          message: Init page is an experimental feature, that may disappear in future releases as well as the flag itself can be changed. Use at your own risk.
-
-      - id: md2
-        type: MarkdownWithCode
-        properties:
-          content: |
-            # Global
-
-            Any data that you wish to use in your app can be stored in the __global__ object, and accessed using the [`_global`](/_global) operator. This is a good place to store data or configuration that is used throughout the app, for example the url of a logo or configuration of a page, since then these are only written once, and can be updated easily.
-
-            The global object can also be modified using the [`SetGlobal`](/SetGlobal) action.
-
-            # Menus
-
-            Menu objects are an object with links to pages. The are used by blocks like `PageSiderMenu` to render the links in the menu. If no menus are provided, a default menu is created, with links to all of the defined pages, and with their pageIds as menu item titles.
-
-            Blocks like like `PageSiderMenu` use the menu with `id: default` by default. This means that if you create a menu object with `id: default`, this will be used unless another menu is configured.
-
-            More than one menu can be configured in an app. As an example, this can be used when two logically different sections in the app need different menus.
-
-            If OpenID Connect authentication and role based authentication is configured, pages that the user is restricted from seeing are filtered from the menu object.
-
-            The schema for a menu object is:
-
-            - `id: string`: __Required__ - A identifier for the menu. If it is `default`, it will be used as default by pages.
-            - `links: object[]`: An array of `MenuLink` or `MenuGroup` objects that form the links in the menu. `MenuGroups` can be two levels deep.
-
-            The schema for a `MenuLink` is:
-            - `id: string`: __Required__ - A identifier for the link unique to the menu.
-            - `type: string`: __Required__ - The type should be `MenuLink`.
-            - `pageId: string`: The id of the page to link to. Used as the title if no title is provided.
-            - `url: string`: An external url to link to.
-            -  `properties: object`: The properties of the menu link. These are:
-                - `title: string`: The title to display for the link.
-                - `icon: string | object`: The name of an [Ant Design Icon](https://ant.design/components/icon/) or properties of an Icon block to use as the icon for the link. The icon is only shown if the link is at the top level of the menu (not in a menu group).
-
-            The schema for a `MenuGroup` is:
-            - `id: string`: __Required__ - A identifier for the group unique to the menu.
-            - `type: string`: __Required__ - The type should be `MenuGroup`.
-            -  `properties: object`: The properties of the menu group. These are:
-                - `title: string`: The title to display for the group.
-                - `icon: string | object`: The name of an [Ant Design Icon](https://ant.design/components/icon/) or properties of an Icon block to use as the icon for the group. The icon is only shown if the group is at the top level of the menu (not in a menu group).
-            - `links: object[]`: An array of `MenuLink` or `MenuGroup` objects that are should be grouped together in the group.
-
-            ###### Menus example:
-            ```yaml
-            lowdefy: LOWDEFY_VERSION
-            menus:
-              - id: default
-                links:
-                  - id: page1
-                    type: MenuLink
-                    pageId: page1
-                    properties:
-                      title: Page 1
-                      icon: AiOutlinedFile
-                  - id: top-group
-                    properties:
-                      title: Group
-                      icon: AiOutlinedGroup
-                    links:
-                      - id: page2
-                        type: MenuLink
-                        pageId: page2 # pageId will be used as link title
-                      - id: external
-                        type: MenuLink
-                        url: https://external.com
-                        properties:
-                          title: External site
-                      - id: nested-group
-                        type: MenuGroup
-                        properties:
-                          title: Nested Group
-                        links:
-                          - id: page3
-                            type: MenuLink
-                            pageId: page3
-                            properties:
-                              title: Page 3
-              - id: page-1-and-3
-                links:
-                  - id: page1
-                    type: MenuLink
-                    pageId: page1
-                    properties:
-                      title: Page 1
-                      icon: AiOutlinedFile
-                  - id: page3
-                    type: MenuLink
-                    pageId: page3
-                    properties:
-                      title: Page 3
-                      icon: AiOutlinedControl
-            ```
-
-            # Pages
-
-            Pages in a Lowdefy app are actually just blocks, the building blocks of a Lowdefy app, with a few extra restrictions and features.
-
-            Each page should have an `id` that is unique among all pages in the app. Each page is served with the `pageId` as the url route. That is, if you create a page with id `page1`, it will be served at `domain.com/page1`.
-
-            Page blocks should be of category `context`, in order to create a context for the page. This means they always have the context initialization events like `onInit` to initialize the page.
-
-            If `properties.title` is set on a page block, the title will be set as the page title (This is the title displayed on the tabs in your browser).
-
-            # References and templates
-
-            References are used to split the configuration of an app into logically distinct files, and to reuse configuration in the app. References can be used almost anywhere in the configuration, as long as the configuration remains valid YAML.
-
-            References are made using the [`_ref`](/_ref) operator. If the referenced file has a `.yaml` or `.json` extension, the contents of the file will be parsed, else the file content is included as a string (this is useful for `.md` or `.html` files). As an example of splitting an app into logically distinct files, references can be used to write each page as a separate file:
-
-            ###### lowdefy.yaml
-            ```yaml
-            lowdefy: LOWDEFY_VERSION
-
-            pages:
-              _ref: pages/page1.yaml # Path to the referenced file. Always from the root of the project.
-              _ref: pages/page1.yaml
-            ```
-
-            The `_ref` operator can take an argument called `vars`. This can be any data, and is passed down to later be accessed with the [`_var`](/_var) operator. By using vars, the referenced file can become a template, using the given variables. For example, a standard page template might be used for multiple pages in an app:
-
-            ###### pages/page1.yaml
-            ```yaml
-            _ref:
-              path: templates/text_page.yaml
-              vars:
-                id: page1
-                title: Page 1
-                content: |
-                  Page content text.
-            ```
-
-            ###### templates/text_page.yaml
-            ```yaml
-            id:
-              _var: id
-            type: PageHeaderMenu
-            properties:
-              title:
-                _var: title
-            blocks:
-              - id: content_card
-                type: Card
-                blocks:
-                  - id: title
-                    type: Title
-                    properties:
-                      content:
-                        _var: title
-                  - id: content
-                    type: Markdown
-                    properties:
-                      content:
-                        _var: content
-            ```
-
-            Templating can be taken further by referencing [Nunjucks](https://mozilla.github.io/nunjucks/) template files. If a file ends with the `.njk` file extension, the file will first be hydrated as a Nunjucks template, using the `vars` as template variables. If the file ends with `.yaml.njk` or `.json.njk`, the output of the template will then be parsed. Nunjucks templates are useful since the template file does not need to be valid yaml before it is hydrated, and features like for-loops and if-statements can be used.
-
-            Templating is used extensively to create the Lowdefy docs (these docs are a Lowdefy app). You can look at how they are used [here](https://github.com/lowdefy/lowdefy/tree/main/packages/docs).
-
-            The `_ref` operator can also be extended with custom JavaScript functions. A `resolver` function can be specified, which can overwrite the default way configuration files are read from the filesystem. A `transformer` function can be used to transform the value returned by the `_ref` operator.
-
-            ## YAML file extensions
-
-            Both files with the `.yaml` and `.yml` file extensions are supported as YAML files.
-
-            ## JSON instead of YAML
-
-            Since you can reference JSON files, you can build your app using JSON instead of YAML files. The `lowdefy.yaml` file needs to be a YAML file, but all other configuration can be in referenced JSON files. It also makes sense to use JSON instead of YAML if you are generating configuration using code.
-
-            # Lowdefy versions and version updates
-
-            Lowdefy is versioned using semantic versioning, with a three part version number, with the form `major.minor.patch`. Lowdefy is in the early stages of development and under active development, with new versions published on a regular basis.
-
-            To update the version of your app, change the `lowdefy` version field in the `lowdefy.yaml` file, and redeploy the app. You might also need to make some changes to your app configuration to be compatible with the new version.
-
-            Patch updates only contain fixes, and you should be safe to update to a patched version without any changes to your app. Since we are actively developing new features, most releases will be minor version updates, and patches won't be made to older versions.
-
-            Minor version changes include new features. At this stage, since the project is still in early development, they might also have minor breaking changes to individual blocks, actions, operators or connections. Please check the [changelog](https://github.com/lowdefy/lowdefy/blob/main/CHANGELOG.md) to see if any configuration changes are needed before updating.
-
-            Major version updates may include major breaking changes or architecture changes. You might need to make more changes to your configuration to be compatible with the new version. We don't intend to release major versions regularly, and try to minimize breaking changes.
-
-            As the project grows, we will release a long term support (LTS) version, that will continue to receive patches, but won't have any breaking changes.
-
-      - _ref:
-          path: templates/navigation_buttons.yaml
-          vars:
-            previous_page_title: The CLI
-            previous_page_id: cli
-            next_page_title: Context and State
-            next_page_id: context-and-state

package/concepts/operators.yaml

@@ -1,66 +0,0 @@
-# Copyright 2020-2021 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: operators
-    pageTitle: Operators
-    section: Concepts
-    filePath: concepts/operators.yaml
-    content:
-      - id: md1
-        type: Markdown
-        properties:
-          content: |
-            Operators are functions, that can be used to express logic. They are the reason why Lowdefy apps are not completely static, but can react to data and inputs. Operators can be used in `blocks`, `actions`, `requests`, and `connections`. See the specific documentation for more details.
-
-            Each operators expects arguments with a specific structure. They can be the result of other operators, since operators are evaluated beginning with the most nested operators.
-
-            If an operator errors while evaluating, it returns a `null` value, and logs the error to the console.
-
-            ## Client or server operators
-
-            Some operators are only available on either the client or the server. For example, the [`_menu`](/_menu) operator is only useful on the client and is thus not included in server requests. Likewise, the [`_secret`](/_secret) operator is only available on the server for security reasons. 
-
-            If a operator has special environment considerations, it is indicated on the individual operator documentation page. If no indication is made, the operator can be used under both environments.
-
-            ##### Client only operators:
-            - [_actions](/_actions)
-            - [_format](/_format)
-            - [_js](/_js)
-            - [_list_contexts](/_list_contexts)
-            - [_media](/_media)
-            - [_menu](/_menu)
-            - [_request](/_request)
-
-            ##### Server only operators:
-            - [_diff](/_diff)
-            - [_secret](/_secret)
-            - [_uuid](/_uuid)
-
-            Operators that are client side only cannot be used in `Requests` and `Connections`, and operators which are server side only cannot be used in `Blocks` and `Actions`. 
-
-            ## Build time operators
-
-            Besides the client and server environment, app build time is considered a third environment where special operator logic applies.
-
-            The `_ref` and `_var` operators do not work like other operators. They are evaluated while an app is being built, and can thus be used anywhere in the app configuration. They are used to split a app into multiple files, and to reuse configuration. See [`_ref`](/_ref) for more details.
-      - _ref:
-          path: templates/navigation_buttons.yaml
-          vars:
-            previous_page_title: Events and Actions
-            previous_page_id: events-and-actions
-            next_page_title: Secrets
-            next_page_id: secrets

package/concepts/overview.yaml

@@ -1,48 +0,0 @@
-# Copyright 2020-2021 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: overview
-    pageTitle: Overview
-    section: Concepts
-    filePath: concepts/overview.yaml
-    content:
-      - id: md1
-        type: Markdown
-        properties:
-          content: |
-            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.
-
-            The diagram below provides an overview of the Lowdefy app schematic:
-            ![Lowdefy App Diagram](https://deploy-preview-481--lowdefy-docs.netlify.app/public/lowdefy_app_schema.png "Lowdefy App Diagram")
-
-            The Lowdefy server manages connections and executes requests, serves a web client, and serves the configuration for app pages to the client. The server does not have a data-store, but can connect to external data sources like APIs and databases.
-
-            The Lowdefy web client manages the layout and loading of Lowdefy blocks. Blocks are loaded to the client using _webpack Module Federation_. This means that Lowdefy blocks are external to your apps and can be hosted separately on any static file server, which allows you to extend Lowdefy's capabilities with custom Lowdefy blocks.
-
-            The client also manages each context in the app, executes actions that are triggered by events, and evaluates operators that allow for "live updates" to the UI.
-
-            Authentication for private pages in Lowdefy apps is implemented by connecting to your preferred, external OpenID Connect provider.
-
-      - _ref:
-          path: templates/navigation_buttons.yaml
-          vars:
-            previous_page_title: Tutorial
-            previous_page_id: tutorial-start
-            next_page_title: The CLI
-            next_page_id: cli

package/concepts/secrets.yaml

@@ -1,56 +0,0 @@
-# Copyright 2020-2021 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: secrets
-    pageTitle: Secrets
-    section: Concepts
-    filePath: concepts/secrets.yaml
-    content:
-      - id: md1
-        type: Markdown
-        properties:
-          content: |
-            The `secrets` object is a object that can be used to securely store sensitive information like passwords and API keys. Secrets can be accessed using the [`_secret`](/_secret) operator.
-
-            The secrets object only exists on the backend server, and therefore the `_secret` operator can only be used in `connections` and `requests`.
-
-            We intend to support multiple secrets strategies in the future (for example AWS Secrets Manager or Docker secrets). Current secrets can only be set with environment variables.
-
-            ## Environment variables strategy
-
-            Secrets can be set by creating an environment variable prefixed with `LOWDEFY_SECRET_`. The secret will then be available in the secrets object with the remaining part ot the name as key.
-
-            For example, if the environment variable `LOWDEFY_SECRET_MY_SECRET` is set to `supersecret`, then `_secret: MY_SECRET` will return `supersecret`.
-
-            Only strings can be set as environment variables. To store a object as a secret, the object can be JSON stringified, and parsed using the `_json.parse` operator.
-
-            To store secrets that contain newline characters, the secret can be base64 encoded, and decoded using the `_base64.decode` operator.
-
-            To use secrets in the local development environment, environment variables can be set using a `.env` file. Create a file called `.env` at the root of the project directory. Then set environment variables as:
-
-            ```
-            # .env
-            LOWDEFY_SECRET_MY_SECRET=supersecret
-            ```
-
-      - _ref:
-          path: templates/navigation_buttons.yaml
-          vars:
-            previous_page_title: Operators
-            previous_page_id: operators
-            next_page_title: Lists
-            next_page_id: lists