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

package/tutorial/tutorial-start.yaml

@@ -1,282 +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: tutorial-start
-    pageTitle: 1. Getting started
-    section: Tutorial
-    filePath: tutorial/tutorial-start.yaml
-    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
-        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).
-
-            ### Requirements
-
-            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.
-
-            #### Step 1.1 - Create a project directory
-
-            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.2 - Open a command line interface
-
-            Open your computer's command line interface (Windows CMD, Terminal on MacOS), and change directory (`cd`) to the project directory.
-
-            #### Step 1.3 - Initialize an app
-
-            Use the Lowdefy CLI to initialize your project.
-
-            Run the following in your terminal:
-
-      - _ref:
-          path: templates/cli_command.yaml.njk
-          vars:
-            id: init
-            command: 'npx lowdefy@latest init'
-
-      - 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.
-
-            > 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: info_windows_paste
-        type: Alert
-        properties:
-          type: info
-          icon: AiFilledInfoCircle
-          description: To paste into the Windows Command Prompt, you can right-click and select paste.
-
-      - id: error_already_exists
-        type: Alert
-        properties:
-          type: error
-          icon: AiOutlinedFire
-          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: body_start_dev
-        type: MarkdownWithCode
-        properties:
-          content: |
-            #### Step 1.4 - Start the development server.
-
-            Run:
-
-      - _ref:
-          path: templates/cli_command.yaml.njk
-          vars:
-            id: dev
-            command: 'npx lowdefy@latest dev'
-
-      - id: body_open_browser
-        type: MarkdownWithCode
-        properties:
-          content: |
-            Your browser should open on http://localhost:3000, and you should see the following:
-
-      - id: example1
-        type: PageHeaderMenu
-        properties:
-          style:
-            minHeight: 300px
-          menu:
-            links:
-              - id: welcome
-                type: MenuLink
-                properties:
-                  title: welcome
-
-        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: AiTwoToneHeart
-                        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: error_could_not_find
-        type: Alert
-        properties:
-          type: error
-          icon: AiOutlinedFire
-          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.
-
-      - id: body_edit
-        type: MarkdownWithCode
-        properties:
-          content: |
-            #### Step 1.5 - Open the configuration file
-
-            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:
-
-            ```yaml
-            lowdefy: 3.23.2
-            name: Lowdefy starter
-
-            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: AiTwoToneHeart
-                                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
-
-            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
-
-            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.
-
-            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.
-
-      - _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

package/users/login-and-logout.yaml

@@ -1,164 +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: login-and-logout
-    pageTitle: Login and Logout
-    section: User Authentication
-    filePath: concepts/login-and-logout.yaml
-    content:
-      - id: introduction
-        type: MarkdownWithCode
-        properties:
-          content: |
-            The [`Login`](/Login) and [`Logout`](/Logout) actions can be used to log users in and out.
-
-            ## Login
-
-            The `Login` action requests the OpenID provider's authorization URL from the Lowdefy server. The user is redirected to this URL, which normally hosts a login page. If the user is already logged in at the provider, the provider might redirect the user back without requiring a password again.
-
-            After the user has logged in successfully, the user is redirected to the `auth/openid-callback` route in the Lowdefy app, where the rest of the OpenID authorization code flow is completed.
-
-            The parameters of the Login action specify where the user is redirected after login is complete. If the pageId is not set, the user is redirected to the homepage. The parameters are:
-            - `authUrlQueryParams: object`: Query parameters to set for the authorization URL.
-            - `pageId: string`: The pageId of the page to redirect to after the login flow is complete
-            - `input: object`: The input to set for the page the user is redirected to after login.
-            - `urlQuery: object`: The urlQuery to set for the page the user is redirected to after login.
-
-            The `Login` action can be used to update the `user` object, for example to update the user profile after it has been edited, or to make sure the user token is still valid before editing or creating a record in a database.
-
-            #### Examples
-
-            ###### A login page that redirects users in the onEnter event:
-            ```yaml
-            id: login
-            type: Context
-            events:
-              onEnter:
-                # Redirect to "page1" if user is already logged in.
-                - id: logged_in_redirect
-                  type: Link
-                  skip:
-                    _eq:
-                      - _user: sub
-                      - null
-                  params: page1
-                # Call the Login action to log the user in.
-                - id: login
-                  type: Login
-                  skip:
-                    _ne:
-                      - _user: sub
-                      - null
-                  params:
-                    # Redirect to "page1" after login is complete.
-                    pageId: page1
-            ```
-
-            ###### A set of login and logout buttons:
-            ```yaml
-            id: login_logout
-            type: Box
-            blocks:
-              - id: Login
-                type: Button
-                visible:
-                  _eq:
-                    - _user: sub
-                    - null
-                events:
-                  onClick:
-                    - id: login
-                      type: Login
-              - id: Logout
-                type: Button
-                visible:
-                  _ne:
-                    - _user: sub
-                    - null
-                events:
-                  onClick:
-                    - id: logout
-                      type: Logout
-            ```
-
-            ###### A signup button that uses authUrlQueryParams to request the signup screen:
-            ```yaml
-            id: Signup
-            type: Button
-            events:
-              onClick:
-                - id: login
-                  type: Login
-                  params:
-                    authUrlQueryParams:
-                      screen_hint: signup
-            ```
-
-            ## Logout
-
-            When the `Logout` action is called, the user data and authorization cookie are cleared by the app. The `Logout` action does not take any parameters. The user is then redirected to the URL configured in `logoutRedirectUri`, or the app homepage if this is not configured.
-
-            Some OpenID Connect providers provide a URL that the user can be directed to to logout the user from the the provider. These urls normally have a query parameter that specifies where the provider should redirect the user after they have logged out the user. These redirect URLs are normally configured with the provider.
-
-            The logoutRedirectUri can be a [Nunjucks](https://mozilla.github.io/nunjucks/) template string, with the following template variables:
-            - `client_id`: The OpenID Connect client ID in `LOWDEFY_SECRET_OPENID_CLIENT_ID`
-            - `host`: The app host URL. This url includes the URL prefix (`https://` or `http://` if running a development server), and is URI encoded. It is intended to be used as a query parameter.
-            - `id_token_hint`: The user idToken.
-            - `openid_domain`: The OpenID Connect client ID in `LOWDEFY_SECRET_OPENID_DOMAIN`.
-
-            #### Examples
-
-            ###### Redirect to the `logged-out` page in the app after logout:
-            ```yaml
-            config:
-              auth:
-                openId:
-                  logoutRedirectUri: '/logged-out'
-            ```
-
-            ###### Redirect to the Auth0 logout URL and return to the `logged-out` page in the app after logout:
-            ```yaml
-            lowdefy: 3.23.2
-            config:
-              auth:
-                openId:
-                  # Line breaks added for clarity
-                  logoutRedirectUri: "{{ openid_domain }}/v2/logout?\
-                    returnTo={{ host }}/logged-out&\
-                    client_id={{ client_id }}"
-            ```
-
-            ###### Redirect to the Keycloak logout URL and return to the `logged-out` page in the app after logout:
-            ```yaml
-            lowdefy: 3.23.2
-            config:
-              auth:
-                openId:
-                  # Line breaks added for clarity
-                  logoutRedirectUri: "{{ openid_domain }}/protocol/openid-connect/logout?\
-                    post_logout_redirect_uri={{ host }}/logged-out&\
-                    client_id={{ client_id }}&\
-                    id_token_hint={{ id_token_hint }}"
-            ```
-
-      - _ref:
-          path: templates/navigation_buttons.yaml
-          vars:
-            previous_page_title: OpenID Connect
-            previous_page_id: openid-connect
-            next_page_title: Protected pages
-            next_page_id: protected-pages

package/users/openid-connect.yaml

@@ -1,84 +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: openid-connect
-    pageTitle: OpenID Connect
-    section: User Authentication
-    filePath: users/openid-connect.yaml
-    content:
-      - id: open_id_connect_content
-        type: MarkdownWithCode
-        properties:
-          content: |
-            Lowdefy supports the OpenID Connect standard as a user authorization mechanism. This means to add users to your app, you should setup a OpenID Connect provider. Some popular providers are:
-
-            - [Auth0](https://auth0.com)
-            - [Gluu](https://gluu.org)
-            - [Keycloak](https://www.keycloak.org)
-            - [Microsoft identity platform](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-overview) (Active Directory)
-            - [Okta](https://www.okta.com)
-            - [Ory Hydra](https://www.ory.sh)
-            - [Ping Identity](https://www.pingidentity.com)
-            - [Sign In With Google](https://developers.google.com/identity) (Google Workspace is also supported)
-
-            A full list of OpenID Connect providers can be found [here](https://openid.net/developers/certified/).
-
-            ## Configuring an OpenID Connect provider
-
-            To configure an OpenID Connect provider, you need to set the following lowdefy [secrets](/secrets): `OPENID_CLIENT_ID`, `OPENID_CLIENT_SECRET`, `OPENID_DOMAIN`, and `JWT_SECRET`. The can be set by setting the following environment variables:
-            ```
-            LOWDEFY_SECRET_OPENID_CLIENT_ID = YOUR_CLIENT_ID
-            LOWDEFY_SECRET_OPENID_CLIENT_SECRET = YOUR_CLIENT_SECRET
-            LOWDEFY_SECRET_OPENID_DOMAIN = YOUR_OPENID_DOMAIN
-            LOWDEFY_SECRET_JWT_SECRET = YOUR_SECRET_KEY
-            ```
-
-            See the section on JSON Web Tokens below for information about the `JWT_SECRET`.
-
-            If these are not set, the `Login` and `Logout` actions won't work, so users won't be able to log in. However, protected pages will not be served to public users.
-
-            Optional configuration can also be set in the Lowdefy configuration, at the path `config.auth.openId`. The following fields can be set:
-
-            - `scope: string`: _Optional_ - The OpenID Connect scope to request. The default is `openid profile email`. Should contain at least `openid`.
-            - `logoutRedirectUri: string`: _Optional_ - The URL to redirect to after logout. See more [here](/login-and-logout).
-
-
-            Details to configure specific OpenID Connect providers are given [here](/openid-provider-configuration).
-
-            # JSON Web Tokens
-
-            The app will use the `JWT_SECRET` to sign the JSON web tokens (with HS256) used to authorize users. This secret should be a long randomly generated string.
-
-            You can run the following command in the command console to generate the key:
-            ```bash
-            node -e "console.log(require('crypto').randomBytes(256).toString('base64'));"
-            ```
-
-            We recommend using a different key in your development and production environments.
-
-            Optional configuration can also be set in the Lowdefy configuration, at the path `config.auth.jwt`. The following fields can be set:
-
-            - `loginStateExpiresIn: string | number`: The length of time an authorization request token should be valid. The default is 5 minutes. If you expect the user will not log-in immediately then you may want to increase this parameter.  Can be expressed as a number in seconds, or a [vercel/ms string](https://github.com/vercel/ms).
-            - `expiresIn: string | number`: The length of time a user token should be valid. The default is 4 hours. Can be expressed as a number in seconds, or a [vercel/ms string](https://github.com/vercel/ms).
-
-      - _ref:
-          path: templates/navigation_buttons.yaml
-          vars:
-            previous_page_title: Introduction
-            previous_page_id: introduction
-            next_page_title: Login and Logout
-            next_page_id: login-and-logout

package/users/protected-pages.yaml

@@ -1,67 +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: protected-pages
-    pageTitle: Protected pages
-    section: User Authentication
-    filePath: concepts/protected-pages.yaml
-    content:
-      - id: introduction
-        type: MarkdownWithCode
-        properties:
-          content: |
-            By default, all the pages in a Lowdefy app are public. Protected pages are pages that can only be accessed by a logged in user. If a user that is not logged in tries to access a protected page, the user will be redirected to the 404 page. Pages that a user is not allowed to see will be filtered from the app menus.
-
-            The config can either be set to protect all pages, except for a list of public pages, or vise-versa, all pages are public except for a a list of protected pages.
-
-            Protected and public pages can be configured at the path `config.auth.pages` in the Lowdefy configuration. Here the fields `protected` and `public` fields can be set to true, or a list of pageIds. You cannot set `protected` or `public` to `false`, and both can't be an array or `true`.
-
-            When protecting all pages in the app, you will need to set at least one as public, to allow users to log in to the app.
-
-            #### Examples
-
-            ###### List specific public pages:
-            ```yaml
-            lowdefy: 3.23.2
-            config:
-              auth:
-                pages:
-                  protected: true
-                  public:
-                    - '404'
-                    - login
-                    - public-page
-            ````
-            ###### List specific protected pages:
-            ```yaml
-            lowdefy: 3.23.2
-            config:
-              auth:
-                pages:
-                  public: true
-                  protected:
-                    - admin
-                    - users
-            ````
-
-      - _ref:
-          path: templates/navigation_buttons.yaml
-          vars:
-            previous_page_title: Login and Logout
-            previous_page_id: login-and-logout
-            next_page_title: User object
-            next_page_id: user-object

package/users/roles.yaml

@@ -1,70 +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: roles
-    pageTitle: Roles
-    section: User Authentication
-    filePath: concepts/roles.yaml
-    content:
-      - id: introduction
-        type: MarkdownWithCode
-        properties:
-          content: |
-            Roles can be used to limit user access to certain pages. Only users with the role will be able to see the page, and the page will be filtered from menus if the user does not have the role.
-
-            Roles can be read from a custom claim on the OpenID Connect `idToken`. This should be an array of strings which are the role names. This needs to be configured at the OpenID Connect provider. The field that contains the roles array is configured in the `config.auth.openId` field in the Lowdefy configuration.
-
-            ```yaml
-            lowdefy: 3.23.2
-            config:
-              auth:
-                openId:
-                  # Field in the user idToken that contains the roles array.
-                  rolesField: [string]
-            ```
-
-            The pages that are protected by roles are configured in the `config.auth.roles` field in the Lowdefy configuration. This should be an object, where the keys are the role names, and the values are an array of pageIds that are protected by that role.
-
-            #### Examples
-
-            ###### Protect pages using roles:
-            ```yaml
-            lowdefy: 3.23.2
-            config:
-              auth:
-                openId:
-                  rolesField: custom_roles
-                roles:
-                  user-admin:
-                    - users
-                    - new-user
-                    - edit-user
-                  sales:
-                    - customers
-                    - new-customer
-                    - edit-customer
-                  reports:
-                    - sales-report
-                    - operations-report
-            ````
-      # - _ref:
-      #     path: templates/navigation_buttons.yaml
-      #     vars:
-      #       previous_page_title: User object
-      #       previous_page_id: user-object
-      #       next_page_title: Provider configuration
-      #       next_page_id: openid-provider-configuration