# OpenFlower overview
## What is OpenFlower?
OpenFlower is an easy-to-use open-source low-code platform to build customer-facing, embeddable Saas applications within minutes.
Traditionally, building an application requires complex frontend and backend interactions with hundreds and thousands of lines of code, not to mention work on packaging, integration, and deployment. OpenFlower significantly reduces the work you need to do to build and publish an application.
In OpenFlower, all you need to do is drag and drop pre-built or self-customized components onto the What-You-See-Is-What-You-Get (WYSIWYG) canvas, along with ready-to-connect databases and APIs, OpenFlower helps you build an app quickly and focus on business logic.
## Why choose OpenFlower?
* **Open source:** For cloud and self-hosted deployment. Makes your ideas more feasible.
* **All-in-one platform:** Connection to all kinds of data sources and APIs such as Databases, Streaming sources, and Restful APIs, and ensures your data security.
* **Embed Apps everywhere:** Apps, that are created with OpenFlower can get embedded natively into Websites, Apps, and Mobile Apps.
* **High scalability:** The deployment options allow a single container image, but also a scalable multi-container deployment, so any kind of load is manageable.
* **Extensibility:** Add functionality in OpenFlower at multiple places. From simple custom components and external libraries to new data source plugins.
* **Clean design:** Follows the principles of [Ant Design](https://ant.design/) and supports display on screens of different sizes for Desktop and Mobile Applications.
* **Built-in features:** Multi-tenant management, Multi-workspaces management, theming, mobile screen, navigation support, fine-grained access control, and audit logs.
## How to build Apps in OpenFlower?
Building an app [Hello World Tutorial](https://github.com/Flowerappeng-org/openflower/blob/main/docs/OpenFlower-overview/the-hello-world-tutorial.md):
* Quickly and securely connect to your data sources, including PostgreSQL, MongoDB, and online APIs.
* Create Data queries visually or by SQL or set up request parameters to connect APIs.
* Use our 100+ UI components to build your app UI and bind and display query data with UI components like Tables, Charts, and Lists.
* Set up event handlers to trigger queries, control components, or other actions in reaction to user interactions.
* Preview and share your app with others.
# The "Hello World" tutorial
A Hello World tutorial
1. At your first contact with OpenFlower you will see the Login Screen.
OpenFlower Login Screen
If you haven't created your account yet, you can register a new account with the url /user/auth/register or the Sign up Link on the login page.
Sign up screen to create a new user.
When you create a User without Invite-Link, this User will automatically get the role of an Administrator with their own Workspace.
The first Screen of the Admin Panel of OpenFlower shows the overview of all Applications (in the current selected Workplace). For new Installations & logins, the Workplace is named by the email of the logged in User.
Application overview as welcome screen
2. In OpenFlower you can create and find the building blocks of applications:
* Navigations
* Mobile Navigations
* Apps
* Modules
* Folder
All these building blocks are displayed on the home screen.\
You can order these building blocks by folders.
Folder for Application building blocks
3. With the help of the blue "New" Button you can select and create a fresh, empty application. You will arrive at the App Editor Screen.
Application Editor - standard screen.
The main screen is divided into 4 sections. To create an Application typically starts to place any component from the red section to the application-space, yellow in the middle of the screen.
4. Components can get placed next to each other or through Layers, so components can visually overlap.
The green area helps you to gather and prepare Data for your Application. Here data queries for multiple datasources as also data transformations and even javascript functions can get managed.
The blue area helps to see a hierarchical view of the components of an application as also to see in realtime their application state with current data and events.
The blue and red area consist of 2 panels between users can switch. (green marked areas)
Screen Settings and Component details
In the blue section, general settings for an application can get managed, such as the applied theme, local Javascript and Style (CSS) embeds as also screen settings for expected resolutions.
In the red section, which opens automatically as soon as you click on a specific component in the application-space, all detail settings for the selected component can be made.
* Data Binding to show selected data with the component
* Event Bindings to take an user event and trigger an action
* Layout Settings to adjust positions for labels, orientation and visibility
* Style Settings to select colors, sizes and margins
5. As soon as you like, you can share an Application with selected users to test together.
You can use the "Share" Button to invite other OpenFlower Users to use the Application
Select individual Users or make the Application public for everyone.
Based on your settings you can invite special users only or make the application public accessible, so everyone can see the application. If you want to invite co-editors for your application, you need to give them the desired rights / role.
After all tests are done, your application is ready to hit the market. You can use the "Preview Button" to explore how your Application looks for a standard logged in user.
6. With the same button, but by help of the small arrow on the right, you can finally publish the application in it's current state. Make sure, the application is then accessible (Share menu) as you expect. (public or for selected users only)
# Videos
Explore our collection of educational videos designed to help you master OpenFlower. Whether you're a beginner or an advanced user, the step-by-step tutorials, feature deep dives, and expert tips will guide you through everything you need to know.
💡 **What You'll Find:**\
✅ Beginner-friendly introductions\
✅ Advanced feature walkthroughs\
✅ Tips and best practices\
✅ Updates on new features
Start learning today and unlock the full potential of OpenFlower!
[Watch OpenFlower in 100 seconds](/readme-1/openflower-100-seconds)
# OpenFlower in 100 seconds
OpenFlower in 100 seconds
{% embed url="" %}
# Cloud & Private Cloud
OpenFlower is available online. You can start directly to build Applications.
[OpenFlower Playground - Start here](https://prod-us1.openflower.org)
We offer a hosted version of OpenFlower in this shared public cloud for free. We take care of updates, security, and scaling of the underlying infrastructure.
The public cloud has a central database for all users and applications. We suggest using the public cloud to get to know OpenFlower and make your first tests and Applications.
OpenFlower is hosted in Google data centers. Backups are organized every night for all infrastructure components and the Databases as Snapshots.
# Self-hosting
In this article, you will be guided through how to host OpenFlower on your own server using Docker-Compose or Docker.
There are multiple ways of installation. We directly support:
* [Single Docker Image](https://github.com/Flowerappeng-org/openflower/deploy/docker) to run with a single line of command.
* Multi-Docker Image deployment for scaling scenarios with [Docker Compose](https://github.com/Flowerappeng-org/openflower/blob/main/deploy/docker/docker-compose-multi.yaml)
* Kubernetes-based deployment with [HELM Charts](https://github.com/Flowerappeng-org/openflower/tree/main/deploy/helm).
* [Heroku based deployment](/setup-and-run/self-hosting/heroku)
* [Google Cloud Platform](/setup-and-run/self-hosting/google-cloud-platform)
## 1) Start easy:
For easy setup and deployment, we provide an [all-in-one image](https://hub.docker.com/r/flowerappengorg/openflower) that bundles frontend, backend, and data persistence services altogether in one single container.
### All-in-one image
#### Prerequisites
* [Docker](https://docs.docker.com/get-docker/) (version 20.10.7 or above)
* [Docker Compose](https://docs.docker.com/compose/install/) (version 1.29.2 or above)
{% hint style="info" %}
Recommended system spec: 1-core CPU and 2 GB RAM.
Windows users are recommended to use PowerShell for running the commands below.
{% endhint %}
In your working directory, run the following commands to make a directory named `OpenFlower` to store the data of OpenFlower:
```bash
mkdir openflower
cd openflower
```
#### Deploy
{% tabs %}
{% tab title="Docker Compose (Recommended)" %}
Follow the steps below:
1. Download the configuration file by clicking [docker-compose.yml](https://raw.githubusercontent.com/Flowerappeng-org/openflower/main/deploy/docker/docker-compose.yaml) or running the curl command:
{% code overflow="wrap" %}
```
curl https://raw.githubusercontent.com/Flowerappeng-org/openflower/main/deploy/docker/docker-compose.yaml -o $PWD/docker-compose.yml
```
{% endcode %}
2. Start the Docker container by running this command:
```bash
docker compose up -d
```
\
The docker image, about 400 MB, is downloaded during the initial start-up.
After downloading, it usually takes less than 30 seconds to start the service.
3. Check the logs by running this command:
```bash
docker logs -f openflower
```
When you see `frontend`, `backend`, `redis`, and `mongo` `entered the RUNNING state`, the OpenFlower service has officially started:
4. Visit [**http://localhost:3000**](http://localhost:3000) and click **Sign up**. OpenFlower will automatically create a workspace for you, then you can start building your apps and invite members to your workspace.
{% endtab %}
{% tab title="Docker" %}
Run the command below:
{% code overflow="wrap" %}
```bash
docker run -d --name openflower -p 3000:3000 -v "$PWD/stacks:/lowcoder-stacks" flowerappengorg/openflower
```
{% endcode %}
{% endtab %}
{% endtabs %}
#### Update to the latest version
{% tabs %}
{% tab title="Docker-Compose" %}
Run the following commands to update to the latest OpenFlower image:
`````bash
docker-compose pull
docker-compose rm -fsv openflower
docker-compose up -d
Run the following commands to update to the latest OpenFlower image:
## 2) Scale
For bigger expected loads that need scaling in a cluster environment: [separate images of backend and frontend services](https://hub.docker.com/u/flowerappengorg) with a customizable Dockerfile.
Multi-Image Installation to scale. API-Service & Node-Service can get scaled independently.
### Separate images: services in stateless containers
For bigger expected loads that need scaling in a cluster environment, we offer separate images for stateless containers of the backend and frontend service with a customizable Dockerfile. A well-functioning OpenFlower deployment consists of below services:
- **api-service**: Backend service.
- **node-service**: Backend service.
- **frontend**: Frontend service.
- **MongoDB**: Used for persisting data of users, apps, data sources, etc.
- **Redis**: Used for maintaining user sessions, rate-limiter, etc.
#### Prerequisites
- [Docker-Compose](https://docs.docker.com/compose/install/) (version 1.29.2 or above)
#### Deploy
1. In your working directory, run the following commands to make a directory named `lowcoder` to store the data of OpenFlower:
```bash
mkdir openflower
cd openflower
```
2. Download the configuration file by clicking [docker-compose-multi.yml](https://github.com/Flowerappeng-org/openflower/blob/main/deploy/docker/docker-compose-multi.yaml) or running the curl command:
3. Modify service configurations in the downloaded Dockerfile according to your needs:
- **mongodb**: Start a new MongoDB instance on your host. You can delete this part and modify the environment variable `MONGODB_URI` of the **api-service** to use your own MongoDB.
- **redis**: Start a new Redis instance on your host. You can delete this part and modify the environment variable `REDIS_URI` of the **api-service** to use your own Redis.
- **api-service**: Required.
- **node-service**: Required.
- **frontend**: Required. Can be optional if you deploy the frontend on CDN.
4. Start Docker containers by running this command:
```bash
docker-compose -f docker-compose-multi.yml up -d
```
5. Visit [**http://localhost:3000**](http://localhost:3000) and click **Sign up**. OpenFlower will automatically create a workspace for you, then you can start building your apps and invite members to your workspace.
## 3) Update to the latest version
Run the following commands to update services to the latest in a Docker Compose installation:
Please also have a look at this [migration / update guide](lowcoder-version-update.md)
```bash
docker-compose -f docker-compose-multi.yml pull
docker-compose -f docker-compose-multi.yml up -d
```
## 4) Customize the deployment
This section shows how to customize deployment configurations by setting environment variables.
If you have already started Docker containers, you need to restart the containers for new configurations to take effect. For example, the way to **restart** your container running an all-in-one image is:
One single command:
```bash
docker-compose down
docker-compose up -d
```
It picks up configuration changes by stopping containers already in service and recreating new ones.
Run the following commands to stop, remove the container already in service, and start up a new one using the newly customized deployment command.
```bash
docker stop openflower
docker rm openflower
# run your new docker run command
```
Below are examples of configuring the all-in-one image by setting environment variables in `docker-compose.yml`. If you are self-hosting with separate images, modify the `openflower-api-service` part of the `docker-compose-multi.yml` file instead.
For more information about configurations and environment variables, see [Configuration](https://github.com/Flowerappeng-org/openflower/tree/main/deploy/docker).
### Use your own MongoDB and Redis
By default, OpenFlower uses the built-in MongoDB and Redis installed inside the container, and you can replace them with your own MongoDB and Redis clusters.
Add environment variables `MONGODB_URI` and `REDIS_URI` in `docker-compose.yml` downloaded in your working directory.\
Add environment variables `MONGODB_URI` and `REDIS_URI` to the deployment command, as shown below:
### Run as non-root user
By default, the supervisor will run under the user `uid=9001`. You can specify the uid by adding a docker environment variable `LOCAL_USER_ID` and setting its value to a different **number**, such as `10010`.
Add an environment variable `LOCAL_USER_ID` in `docker-compose.yml` downloaded in your working directory.\
Add an environment variable `LOCAL_USER_ID` to the deployment command, as shown below:
## 5) Secure your deployment
### Install SSL certificate
With an SSL certificate, you can securely visit self-hosted OpenFlower with HTTPS protocol. Here are the steps to install your SSL certificate before starting a container:
1. Copy `fullchain.pem` and `privkey.pem` to the `$PWD/stacks/ssl` directory.
2. In `$PWD/docker-compose.yml`, change the value of `ports` to `"3443:3443"`.\
1. Copy `fullchain.pem` and `privkey.pem` to the `$PWD/stacks/ssl` directory.
2. Change the `ports` in the deployment command to `3443:3443`, as shown below:
In cases where you have certificates with names: `server.crt` and `server.key`, you need to rename them first as follows:\
`server.crt` => `fullchain.pem`\
`server.key` => `privkey.pem`
## 6) Configure the Environment
ENV Variables for Helm, Docker Compose, and Docker installations are to find in the most current version on our Github Repository.
### ENV Variables for the all-in-one image
This image contains all services needed to run OpenFlower platform in one container.
Environment variable
Description
Default-Value
LOWCODER_REDIS_ENABLED
If true redis server is started in the container
true
LOWCODER_MONGODB_ENABLED
If true mongo database is started in the container
true
LOWCODER_MONGODB_EXPOSED
If true mongo database accept connections from outside the docker
false
LOWCODER_API_SERVICE_ENABLED
If true openflower api-service is started in the container
true
LOWCODER_NODE_SERVICE_ENABLED
If true openflower node-service is started in the container
true
LOWCODER_FRONTEND_ENABLED
If true openflower web frontend is started in the container
true
LOWCODER_PUID
ID of user running services. It will own all created logs and data.
SAAS to activate, ENTERPRISE to switch off - Workspaces
SAAS
LOWCODER_EMAIL_SIGNUP_ENABLED
Control if users create their own Workspace automatic when Sign Up
true
LOWCODER_CREATE_WORKSPACE_ON_SIGNUP
IF LOWCODER_WORKSPACE_MODE = SAAS, controls if a own workspace is created for the user after sign up
true
LOWCODER_MARKETPLACE_PRIVATE_MODE
Control if not to show Apps on the local Marketplace to anonymous users
true
Also, you should set the API-KEY secret, whcih should be a string of at least 32 random characters On linux/mac, generate one eg. with: head /dev/urandom | head -c 30 | shasum -a 256
Environment variable
Description
Default-Value
LOWCODER_API_KEY_SECRET
String to encrypt/sign API Keys that users may create
### ENV Variables for the api-service image
Environment variable
Description
Default-Value
LOWCODER_PUID
ID of user running services. It will own all created logs and data.
SAAS to activate, ENTERPRISE to switch off - Workspaces
SAAS
LOWCODER_EMAIL_SIGNUP_ENABLED
Control is users can create their own Workspace when Sign Up
true
### ENV Variables for the node-service image
Environment variable
Description
Default-Value
LOWCODER_PUID
ID of user running services. It will own all created logs and data.
9001
LOWCODER_PGID
ID of group of the user running services.
9001
LOWCODER_API_SERVICE_URL
OpenFlower API service URL
http://localhost:8080
### ENV Variables for the web frontend image
Environment variable
Description
Default-Value
LOWCODER_PUID
ID of user running services. It will own all created logs and data.
9001
LOWCODER_PGID
ID of group of the user running services.
9001
LOWCODER_MAX_QUERY_TIMEOUT
OpenFlower max query timeout (in seconds)
120
LOWCODER_MAX_REQUEST_SIZE
OpenFlower max request size
20m
LOWCODER_API_SERVICE_URL
OpenFlower API service URL
http://localhost:8080
LOWCODER_NODE_SERVICE_URL
OpenFlower Node service (js executor) URL
http://localhost:6060
## Health checks
The API Service has an included health check endpoint from v2.4.1 on.
You can check the health of the running API Service and it's connected MongoDB & Redis by the following HTTP Call:
````bash
```
GET /api/status/health HTTP/1.1
```
`````
In response, you will get a 200 Status code if the service is up and running and a JSON like this:
```json
{
"status": "UP",
"components": {
"mongo": {
"status": "UP",
"components": {
"reactiveMongoSlaveTemplate": {
"status": "UP"
},
"reactiveMongoTemplate": {
"status": "UP"
}
}
},
"ping": {
"status": "UP"
},
"redis": {
"status": "UP"
}
}
}
```
{% endtab %}
{% endtabs %}
# Access local database or API
By default, docker-hosted instances use a [bridge network](https://docs.docker.com/network/bridge/), which does not support access to services on the docker-host via `127.0.0.1` or `localhost` from inside of the docker.
Here we take PostgreSQL as an example and show you how to access local API or database in different operating systems (OS) for docker-hosted OpenFlower.
## Preparation
Assume that a Postgres service is ready on your local host with port `5432`.
On Linux, you can check if Postgres runs locally with the command\
`pgrep -u postgres -fa -- -D`
## How to access a local database or API from OpenFlower which runs inside the Docker
{% tabs %}
{% tab title="Linux" %}
1. Enter `ifconfig docker0` in the terminal, and verify the IP configuration of Docker's virtual bridge (VB).
Having set up Docker, the OS would automatically create `docker0` using the IP address `172.17.0.1` (by default), through which the Docker service communicates with the host.
2. Enter the same IP address into OpenFlower to configure the Postgres data source (`172.17.0.1` in this example, but use the actual IP address displayed on your terminal in the real case).
{% hint style="warning" %}
On some OS (such as Ubuntu), port access might be blocked by the firewall. To solve that, configure in the following steps:
1. Stop the firewall from blocking access from `docker0` by typing in the terminal:\ `iptables -A INPUT -p tcp -i docker0 --dport YOUR_DB_PORT -j ACCEPT`\
`Note: In this case`Here we use Postgres port `5432` for `YOUR_DB_PORT`, and you should replace it with your own.
2. Save the firewall configuration by typing in the terminal:\ `iptables-save > /etc/iptables.up.rules`
{% endhint %}
{% endtab %}
{% tab title="Windows & Mac" %}
On Windows and macOS, Docker does not create the virtual bridge `docker0`. Then the following host name is helpful to resolve the host IP:
```
host.docker.internal
```
{% endtab %}
{% endtabs %}
On Windows and Mac:
Access a Database on your local network from OpenFlower which runs in Docker
Access an API on your local network from OpenFlower which runs in Docker
# Google Cloud Platform
How to Setup Seperate Images on Google Cloud Platform
## Google Cloud Console OpenFlower Setup
### Creating a VPC Network
1. In the Google Cloud Console, in VPC Network, click on VPC Networks
* Enable Compute Engine API
2. Create a VPC Network
* Name the VPC Network
* Disable IPv6
* Create a custom subnet
* Name the subnet
* Choose the region best for your
* Choose an IP Range
* Private Google Access: On
* Flow Logs: Off
* In the subnet, setting turn on Private Google Access (it is necessary to enable this setting otherwise the cloud-run services will not be able to communicate with one another)
* This will be in the Edit subnet section using a custom subnet creation mode
* If the subnet creation mode is automatic, you will have to go to the region of your VPC network and enable the Private Google Access setting from there once the VPC is created.
### Creating a Serverless VPC Access Connector
1. In the VPC Network, create a Connector
* Enable serverless VPC access API
2. Create a Serverless VPC Connector
* Name the Serverless VPC Connector
* Choose the same region as the VPC Network
* Network: Select the VPC Network that was previously created
* Subnet:
* Custom IP range
* IP range (cannot be the same subnet that was created before)
### Creating a Cloud NAT
* Creating a Cloud NAT is necessary because when connecting the lowcoder services to MongoDB, you must whitelist an IP address that can access the MongoDB cluster.
* Google Cloud services will use different IP addresses each time to communicate with the internet unless a Cloud NAT is set up on the VPC
1. Within the “Network Services” in the Google Cloud Console click on “Cloud NAT” and then “Create Cloud NAT gateway”
2. Name the Cloud NAT gateway
3. Set the NAT type to public
4. Select a Cloud Router
* Connect it to the VPC Network created previously
* Select the region for your Router (the one VPC are running on)
* Create a New Router
* Name the router
5. Cloud NAT mapping
* Source: Primary and secondary ranges for all subnets
* Cloud NAT IP Addresses: Manual
* IP Addresses:
* Premium Network Service Tier
* IP address:
* Create and Name an IP address and then click on “Reserve”
* IP draining: Off (default)
6. Click on Create Cloud NAT
7. After creating a Cloud NAT IP address, whitelist this IP address on your MongoDB cluster
### Creating a Redis Instance
1. Within Google Cloud Console in Memorystore, on the Redis page, create a Redis instance
2. Enable Google Cloud Memorystore for Redis API
3. Create a Redis Instance:
* Name Redis instance in the Instance ID
* Basic Tier
* 1 GB of capacity is more than sufficient in our environment however if you face trouble then you can always adjust the capacity as necessary
* Choose the same region as the VPC Network
* Set up Connection: connect your Redis instance to the VPC network created previously
### Setting up the Node Service
1. In the Google Console go to Cloud Run
2. Create a Service
3. In the Container Image URL input: flowerappengorg/openflower-node-service
* This is from the lowcoder docker hub ()
4. Select the Region, same as the region for the VPC Network
5. CPU allocation and pricing: CPU is only allocated during request processing
6. Ingress Control is set to Internal (this is necessary to not expose the Node Service to the rest of the internet)
7. Authentication: Allow unauthenticated access invocations
#### Container Settings
1. Container port: 6060
2. CPU allocation:
* Only allocated during the request processing
3. Capacity (allocate as necessary)
* Memory: 1 GiB
* CPU: 1
4. Execution environment: Default
5. Environment Variable:
* Name 1: LOWCODER\_API\_SERVICE\_URL
* Value 1: Paste the API Service URL (Once the API Service is created after the next step
#### Networking Settings
* Connect to a VPC for outbound traffic
* Use Serverless VPC Access Connectors
* Network: Select the VPC network that was created
* Traffic routing:
* Route only requests to private IPs to the VPC (this is necessary to not expose the Node Service to the rest of the internet)
### Setting up the API Service
1. In the Google Console go to Cloud Run
2. Create a Service
3. In the Container Image URL input: flowerappengorg/openflower-api-service
* This is from the lowcoder docker hub ()
4. Select the Region, same as the region for the VPC Network
5. CPU allocation and pricing: CPU is only allocated during request processing
6. Ingress Control is set to Internal (this is necessary to not expose the API Service to the rest of the internet)
7. Authentication: Allow unauthenticated access invocations
#### Container Settings
1. Container port: 8080
2. Capacity (allocate as necessary)
* Memory: 1 GiB
* CPU: 1
3. Execution environment: Second generation
4. Environment Variable: add any other environment variable as per your requirement (list of environment variables )
* Variable 1:
* Name 1: REDIS\_URL
* Value 1: use: redis\://10.0.0.0:6379?db=databasename and replace 10.0.0.0 with your Redis instance IP address and database name with the name of your database
* Variable 2:
* Name 2: MONGODB\_URL
* Value 2: Paste the MongoDB URL
* Variable 3:
* Name 3: LOWCODER\_NODE\_SERVICE\_URL
* Value 3: Paste the Node Service URL
* Variable 4:
* Name 4: ENABLE\_USER\_SIGN\_UP
* Value 4: TRUE
* If it is a new setup then set it to true; if it will be used for an existing setup then set it to FALSE
* Variable 5:
* Name 5: ENCRYPTION\_PASSWORD
* Value 5: lowcoder.org
* Variable 6:
* Name 6: ENCRYPTION\_SALT
* Value 6: lowcoder.org
* Variable 7:
* Name 7: CORS\_ALLOWED\_DOMAINS
* Value 7: \*
#### Networking Settings
* Connect to a VPC for outbound traffic
* Use Serverless VPC Access Connectors
* Network: Select the VPC network that was created
* Traffic routing:
* Route all traffic to the VPC
### Setting up the Front-End Service
1. In the Google Console go to Cloud Run
2. Create a Service
3. In the Container Image URL input: flowerappengorg/openflower-frontend
* This is from the lowcoder docker hub ()
4. Select the Region, same as the region for the VPC Network
5. CPU allocation and pricing: CPU is only allocated during request processing
6. Ingress Control is set to all (the front-end should be exposed to the internet)
7. Authentication: Allow unauthenticated access invocations
#### Container Settings
1. Container port: 3000
2. Capacity (allocate as necessary)
* Memory: 512 MiB
* CPU: 1
3. Execution environment: Default
4. Environment Variable: add any other environment variable as per your requirement (list of environment variables )
* Variable 1:
* Name 1: LOWCODER\_API\_SERVICE\_URL
* Value 1: Paste the API Service URL
* Variable 2:
* Name 2: LOWCODER\_NODE\_SERVICE\_URL
* Value 2: Paste the Node Service URL
#### Networking Settings
* Connect to a VPC for outbound traffic
* Use Serverless VPC Access Connectors
* Network: Select the VPC network that was created
* Traffic routing:
* Route all traffic to the VPC
#### Post Deployment Settings
* Can set up a DNS for the front URL through Google Domains
Author: Eshaan V Saxena, (10/10/2023)
# Heroku
## Deploy
1. [Sign up](https://signup.heroku.com/) for a new Heroku account, or [log in](https://id.heroku.com/login) to get started.
2. Click to start Heroku [one-click deployment](https://heroku.com/deploy?template=https://github.com/flowerappeng-org/OpenFlower).
3. Set the **App name** which will be part of the app URL later, and choose a region.
4. (Not required) Fill in the **Config Vars** according to the descriptions. These are all optional variables used for environment-specific configuration. You can skip this step and manage environment variables later.
5. Click the **Deploy app** button.
It usually takes around three minutes to start the app.
Click the **View** button to open the new app, which should be available at ****.
On the welcome page, Click **Sign up** to get started. OpenFlower will automatically create a workspace for you. Then you can start building your apps and invite members to your workspace.
## Configure app settings
On the [Heroku Dashboard](https://dashboard.heroku.com/apps), go to the **Settings** tab at the top to configure app settings.
### Manage environment variables
You can manage the environment variables of your app in the **Config Vars** section.
{% hint style="info" %}
For more help, see [Managing config vars](https://devcenter.heroku.com/articles/config-vars#managing-config-vars) in the Heroku documentation.
{% endhint %}
### Install SSL Certificates
You can configure the SSL Certificates of your app in the **SSL Certificates** section. Heroku provides [Automated Certificate Management (ACM)](https://devcenter.heroku.com/articles/automated-certificate-management) and [Manual Certificate](https://devcenter.heroku.com/articles/ssl#manually-uploading-certificates-and-intermediaries) options.
Choose **Manual Certificate**, and you can install your SSL Certificates. A public certificate file usually ends in `.pem` or `.crt`.\\
### Customize domain names
1. Click the **Add Domain** button in the **Domains** section.
2. Fill in your **Domain name** and click **Next**.\\
3. Copy and paste the **DNS Target** provided by Heroku to complete the domain setup.
{% hint style="info" %}
For more help, see [Custom Domain Names for Apps](https://devcenter.heroku.com/articles/custom-domains) in the Heroku documentation.
{% endhint %}
## Update using Heroku CLI
You can use the [Heroku CLI](https://devcenter.heroku.com/categories/command-line) to update your Docker image to the latest version. The basic logic behind the following steps is to pull the newest code from the GitHub repository, build an image locally using the Docker engine, and deploy the updated image using the Heroku CLI. Before you start, make sure you have [Heroku CLI](https://devcenter.heroku.com/categories/command-line) and [Docker](https://www.docker.com/) installations locally (required).
1\. Get the latest code by cloning the [`OpenFlower-org/OpenFlower`](https://github.com/Flowerappeng-org/openflower) repository from GitHub.
```bash
git clone https://github.com/Flowerappeng-org/openflower
```
2\. Move to the `heroku` folder.
```bash
cd OpenFlower/deploy/heroku
```
3\. Log in to Heroku CLI.
```bash
heroku login
```
4\. Make sure you have a Docker engine running locally. Then log in to Container Registry.
```bash
heroku container:login
```
5\. Get the app name of your Heroku account.
```bash
heroku apps
```
6\. Build the image and push it to Container Registry.
```bash
heroku container:push web -a your_app_name
```
7\. Release the image to your app.
```bash
heroku container:release web -a your_app_name
```
It might take a few minutes to build the new image and push it to Heroku. Then you can open the app in your browser to check if it is running.
```bash
heroku open -a your_app_name
```
# Migration from Openblocks
With **OpenFlower v1.1.8** we created a drop-in replacement for **Openblocks** **v1.1.8**.\
To run it, no changes were required.
However, to **migrate** from Openblocks or OpenFlower 1.1.8 to **OpenFlower 2.0,0**, some changes are required and these are the steps to be followed:
### Migrating from Openblocks (or OpenFlower v1.1.8) to **OpenFlower v2.0.0**
{% hint style="info" %}
if not using OpenFlower v1.1.8 or the latest Openblocks released version (v1.1.8), please upgrade first to Openblocks v1.1.8
{% endhint %}
### 1) stop your Openblocks/OpenFlower:
{% tabs %}
{% tab title="All-in-one Docker image" %}
`docker compose down`
{% endtab %}
{% tab title="Multi-Image Deployment" %}
`docker compose -f docker-compose-multi.yaml down`
{% endtab %}
{% endtabs %}
### 2) create a backup copy of the **openblocks-stacks** folder
### 3) rename the **openblocks-stacks** folder to **lowcoder-stacks**
\
`mv openblocks-stacks lowcoder-stacks`
### 4) Download the latest docker-compose file.
download [docker-compose.yaml](https://raw.githubusercontent.com/lowcoder-org/lowcoder/main/deploy/docker/docker-compose.yaml) or [docker-compose-multi.yaml](https://raw.githubusercontent.com/lowcoder-org/lowcoder/main/deploy/docker/docker-compose-multi.yaml) file depending on which installation you prefer (all-in-one or multi-images)\\
### 5) Adapt standard values to your Installation
Edit the docker-compose file and make sure to update these settings - values have to match exactly what you had in your Openblocks version:
```
ENCRYPTION_PASSWORD:
ENCRYPTION_SALT:
MONGODB_URL:
```
### 6) start your OpenFlower
{% tabs %}
{% tab title="All-in-one Docker image" %}
`docker compose up -d`
{% endtab %}
{% tab title="Multi-Image Deployment" %}
`docker compose -f docker-compose-multi.yaml up -d`
{% endtab %}
{% endtabs %}
# Update MongoDB Versions
## Version Update of MongoDB
MongoDB stopped the support for versions < 5 already and will stop the support for version < 6 soon. It is suggested to update the MongoDB Server / Infrastructure.
The lowcoder application continues to operate smoothly on MongoDB version 4.4. However, to ensure compatibility with official MongoDB releases, an update is necessary. This update is specifically required for the all-in-one deployment of lowcoder, which includes MongoDB.
It is important to note that MongoDB version 5.0 and above requires the AVX (Advanced Vector Extensions) feature of the processor. While this feature is standard in all newer processors, it may not be supported by older hardware. Therefore, users with older systems might encounter issues running MongoDB 5.0+.
An incremental update procedure is possible without losing data. However, the major versions of MongoDB cannot be overjumped. You cannot jump to v 6 from v 4; you would first need to adapt to v 5.
Suppose you currently run v4 and want to update to v7- these are the necessary steps for the all-in-one docker image. If you operate a multi-image installation, adap the paths to your data location for your MongoDB and the database must be stopped before the process is started.
### 1) Stop OpenFlower
Stop your OpenFlower instance and wait for it to completely stop the service.
```bash
docker compose down
```
### 2) Create a Backup Copy of the **lowcoder-stacks** folder
```bash
cp -rp lowcoder-stacks lowcoder-stacks.backup
```
### 3) Run upgrade-mongo-4x-to-5x docker compose file
{% file src="/files/YFG38tL85H621s85KpI7" %}
Update MongoDB from v4 to v5
{% endfile %}
```bash
docker compose -f upgrade-mongo-4x-to-5x.yaml up -d && sleep 30
```
### 4) Set MongoDB Compatibility-Version to 5
```bash
docker exec mongodb-5 /usr/bin/mongosh --eval 'use admin' --eval 'db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )'
```
### 5) Stop and remove MongoDB 5 Update-Container
```bash
docker compose -f upgrade-mongo-4x-to-5x.yaml down
```
### 6) Run upgrade-mongo-5x-to-6x docker compose file
{% file src="/files/lgLvkXeKLIxBR2N137Lr" %}
Update MongoDB from v5 to v6
{% endfile %}
```bash
docker compose -f upgrade-mongo-5x-to-6x.yaml up -d && sleep 30
```
### 7) Set MongoDB Compatibility-Version to 6
```bash
docker exec mongodb-6 /usr/bin/mongosh --eval 'use admin' --eval 'db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )'
```
### 8) Stop and remove MongoDB 6 Update-Container
```bash
docker compose -f upgrade-mongo-5x-to-6x.yaml down
```
### 9) Run upgrade-mongo-6x-to-7x docker compose file
{% file src="/files/5a4bH1L1kIEvFWnSWsjy" %}
Update MongoDB from v6 to v7
{% endfile %}
```bash
docker compose -f upgrade-mongo-6x-to-7x.yaml up -d && sleep 30
```
### 10) Stop and remove MongoDB 7 Update-Container
```bash
docker compose -f upgrade-mongo-6x-to-7x.yaml down
```
As result your MongoDB is now updated to Version 7 without Data loss.
# OpenFlower Version Update
## OpenFlower Versioning Scheme
We try to respect as good as possible the Semantic Versioning for OpenFlower Versions
v2.4.1 for example, means:
* Major Version **"2"**. It changes when there are truly big updates that might break old features or add significant new ones. It comes when we introduce fundamentally new concepts inti the Software
* Minor Version **"4"**. It changes when new features are added in a way that doesn’t break existing ones. It should be possible to update the version and expect a working continuation of existing apps.
* Patch Version **"1"**. It changes when we do bug-fixes or improvements, that don't affect overall functionality.
We work with initiatives to add new functionality. This comes normally with the increase of the minor version. When we have a new bigger feature set ready, we introduce it as 2.4.0 for example. The Patch Version is "0". This updates should work in general, but we never can fully exclude not having introduced bugs or unexpected behaviour. Naturally we increase every day the tests and production quality and invest a lot of development time to keep also new features backward compatible.
{% hint style="warning" %}
It is suggested to test a new Minor Version with a Patch Version "0" separately as a Test-Installation. We do not suggest to update this simply on the existing older version.
{% endhint %}
After a new Minor Version we deliver typically the next patch version quite fast, considering all bugs, that we found or that was reported. The first and second Patch Versions we can count in typical cases as Stabe Versions.
{% hint style="info" %}
The patch versions > 0 are typically seen as Stable Version. It should be ok to install these directly as update.
{% endhint %}
### OpenFlower SDK
The SDK has an independent versioning - yet still following the Semantic Versioning Scheme.
Since OpenFlower v2.4.0 we follow the principle, that the SDK will have the same Major and Minor Version as the Main OpenFlower Version - but it can have an independent Patch-Version.
### External Component Plugins
Also external Component Plugins follow the Sematic Versioning Scheme with Major, Minor, and Patch versions. However, they are independent from the OpenFlower or OpenFlower SDK Versions.
### Docker Images
The provided Docker Images from OpenFlower-Org follow the Sematic Versioning of OpenFlower. For every Release of the Codebase with a new Version, we also offer the pre-built Docker Containers for the All-in-one and Multi-Docker installation.
{% embed url="" %}
OpenFlower pre-built Docker Images on Docker Hub
{% endembed %}
Next to the released Version Tags of OpenFlower there are 2 more tags with relevance:
* /latest - These images contain typically a state of development which is somewhat stable - but not yet a released Patch Version. Critical Bugs, that we solved are fastest to get in the /latest tag. The /latest tag always based on the previous last published Patch Version.
* /dev - these images can be seen like Nightly Builds. They contain evetually the latest stage of our development and are only for testing purposes.
{% hint style="danger" %}
Do not use a /dev tag image in production. These images are only to use in test installations aside.
{% endhint %}
{% hint style="info" %}
We suggest only a Multi-Docker Image installation for Production use. The all-in-one image "flowerappengorg/openflower" is suitable to test and introduce OpenFlower in an easy way.
{% endhint %}
## Version Update
To **update** from an older to a newer version or OpenFlower, please follow this guide:
{% hint style="warning" %}
Please always make a Backup / Copy of your /lowcoder-stacks folder.
{% endhint %}
The magic behind an easy update is to make use of the /lowcoder-stacks mounted folder in the docker installations. That enables you to change the Versions of OpenFlower but not touch the Application Data. In the mounted /lowcoder-stacks folder, all MongoDB application data as also Logs and Assets are stored.
In other words, if you not use an external MongoDB Service, the OpenFlower MongoDB stores the Application Data of all your workspaces and Apps there, enabling you to exchange the docker without needing further backup and restore actions.
Based on the lowcoder-stacks folder, the data of a OpenFlower Installation can be transitioned without losses when you update to a new version of OpenFlower.
This deletes the current Conatiner Instance - not the Docker Image itself.
Stop and delete the "Container" you did run based on the old version.
{% hint style="info" %}
If you did follow the /lowcoder-stacks folder mounting, no data would be lost.
{% endhint %}
### 2) Create a backup copy of the **lowcoder-stacks** Folder
Even if it should be never a problem, still we ask you kindly always to make a copy of the whole folder. Sometimes we have no other channce than to introduce breaking changes and we want to make sure you will never loss any data.
### 3) Download the latest OpenFlower Docker images.
#### With Docker Compose
download [docker-compose.yaml](https://raw.githubusercontent.com/lowcoder-org/lowcoder/main/deploy/docker/docker-compose.yaml) or [docker-compose-multi.yaml](https://raw.githubusercontent.com/lowcoder-org/lowcoder/main/deploy/docker/docker-compose-multi.yaml) file depending on which installation you prefer (all-in-one or multi-images)
#### With pure Docker
If you use Docker Desktop, you can pull the /latest tag or a specific version tag.
### 4) Adapt standard values to your Installation
{% hint style="warning" %}
For every Major Version, we likely introduce new ENV Variables. This is the reason to download the latest docker compose file. Naturally, you also can update your local copy with the new ENV Variables and other new config structures.
{% endhint %}
Edit the docker-compose file to your needs, but make sure to update only the settings. The following values must match your previous version to keep the OpenFlower MongoDB accessible for your stored Data Source Secrets.
* LOWCODER\_DB\_ENCRYPTION\_PASSWORD
* LOWCODER\_DB\_ENCRYPTION\_SALT
{% hint style="info" %}
If you lose or change the Encryption Password & Salt, the OpenFlower Database on MongoDB will work as expected - only the existing stored Credentials to Data Sources are "lost" / not accessible.
{% endhint %}
### 5) Run the new OpenFlower Docker-Image
After the image is pulled, you can run the image (create a new container) and configure directly the Ports as well as the ENV Variables.
{% hint style="warning" %}
Mind to re-connect (mount) the /lowcoder-stacks folder
{% endhint %}
#### With Docker Compose
{% tabs %}
{% tab title="All-in-one Docker image" %}
`docker compose up -d`
{% endtab %}
{% tab title="Multi-Image Deployment" %}
`docker compose -f docker-compose-multi.yaml up -d`
{% endtab %}
{% endtabs %}
## Multi Image Docker Version handling
Technically, the Docker Versions and releases go "Hand in Hand". That means that you should always operate the same backend version of API-Service-Image & Node-Service-Image as the Frontend-Image. However, in special situations, the separation of these concerns into different images gives you a degree of freedom to update only one of the images and check the compatibility.
# Traefik loadbalancer
Thanks to the amazing contribution of OpenFlower can work smoothly with the Traefik as Loadbalancer.
This is a docker-compose.yaml file, which shows the necessary settings.
```yaml
version: "3"
services:
## Start OpenFlower (all-in-one)
lowcoder-api-service:
image: flowerappengorg/openflower:latest
container_name: lowcoder
environment:
REDIS_ENABLED: "true"
MONGODB_ENABLED: "true"
API_SERVICE_ENABLED: "true"
NODE_SERVICE_ENABLED: "true"
FRONTEND_ENABLED: "true"
PUID: "1000"
PGID: "1000"
DEFAULT_ORGS_PER_USER: 100
DEFAULT_ORG_MEMBER_COUNT: 1000
DEFAULT_ORG_GROUP_COUNT: 100
DEFAULT_ORG_APP_COUNT: 1000
DEFAULT_DEVELOPER_COUNT: 50
MONGODB_URL: "mongodb://localhost:27017/lowcoder?authSource=admin"
REDIS_URL: "redis://localhost:6379"
ENABLE_USER_SIGN_UP: "false"
ENCRYPTION_PASSWORD: "somethingveryunique"
ENCRYPTION_SALT: "somethingalsounique"
CORS_ALLOWED_DOMAINS: "*"
LOWCODER_API_KEY_SECRET: "b37717ee6de1003921c4445a3088af17ee316a6fad270737282a8ce2acf29832"
LOWCODER_API_SERVICE_URL: "http://localhost:8080"
LOWCODER_NODE_SERVICE_URL: "http://localhost:6060"
LOWCODER_MAX_REQUEST_SIZE: 20m
LOWCODER_MAX_QUERY_TIMEOUT: 120
volumes:
- ./lowcoder-stacks:/lowcoder-stacks
restart: unless-stopped
labels:
- traefik.docker.network=traefik
- traefik.port=3000
- traefik.port=3443
- "traefik.enable=true"
- "traefik.http.routers.lowcoder.rule=Host(`lowcoder.domain.tld`)"
- "traefik.http.routers.lowcoder.entrypoints=websecure"
- "traefik.http.routers.lowcoder.tls.certresolver=letsencrypt"
- "traefik.http.services.lowcoder.loadbalancer.server.port=3000"
networks:
- traefik
networks:
traefik:
external: true
```
# SMTP Server
To enable a secure Password Reset Flow and a future eMail check on Sign-up, you need your own SMTP Server ready. To configure the SMTP Server, you can use the following ENV Variables at the **API-Server Image**.
Environment Variable
Description
Default Value
LOWCODER_ADMIN_SMTP_HOST
SMTP Hostname of your Mail Relay Server
LOWCODER_ADMIN_SMTP_PORT
Port number for the SMTP service
587
LOWCODER_ADMIN_SMTP_USERNAME
Username for SMTP authentication
LOWCODER_ADMIN_SMTP_PASSWORD
Password for SMTP authentication
LOWCODER_ADMIN_SMTP_AUTH
Enable SMTP authentication
true
LOWCODER_ADMIN_SMTP_SSL_ENABLED
Enable SSL encryption
false
LOWCODER_ADMIN_SMTP_STARTTLS_ENABLED
Enable STARTTLS encryption
true
LOWCODER_ADMIN_SMTP_STARTTLS_REQUIRED
Require STARTTLS encryption
true
# Security
## Does OpenFlower store data from my data sources?
No, OpenFlower doesn't store any data returned from your APIs or database queries. Only the connection data of your created Datasources are stored and encrypted.
OpenFlower only serves as a proxy between the client side and your data sources. When you query your APIs or databases, the OpenFlower server connects to the data source with your credentials, forwards the request, and returns the result data to the browser. During the whole process, OpenFlower doesn't store any data from your requests or responses.
OpenFlower also provides a self-hosted version. You can deploy self-hosted OpenFlower images on your own device, on-premise deployment ensures you have total control over your resources and that your data is securely stored.
## Is it safe to log in to my databases on OpenFlower?
Yes, it is safe for the following reasons:
* All sensitive credentials, such as database passwords, are encrypted with [AES-256 encryption](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard).
* Sensitive credentials will never be sent to the browser from the server. They are only used at the server side (in the API service) and are never exposed to the browser, the browser will display "Encrypted on the server side" as a placeholder for existing Datasources.
## Other security measures within OpenFlower
OpenFlower provides secure-by-default service.
* All connections on OpenFlower Cloud are encrypted with [TLS](https://en.wikipedia.org/wiki/Public_key_certificate).
* Sensitive credentials, such as database access credentials, are encrypted with AES-256.
* Self-hosted OpenFlower instances can be configured with unique encryption salt values.
* OpenFlower Cloud only connects to your databases or APIs through allowed IPs, ensuring that your data won't be exposed to unknown IPs while using our cloud service.
## Feedback
Should you have any questions about data security in OpenFlower, please feel free to contact us. We welcome any feedback on our service from security experts and all users.
# Workspaces
OpenFlower supports Workspaces. These are isolated rooms to organize:
* User-Groups
* Users
* [Data Sources](/connect-your-data/data-source-basics)
* [Predefined Data Queries](/workspaces-and-teamwork/query-library)
* [Apps](/build-applications/create-a-new-app) & App Folders
* [Themes](/build-applications/themes-and-styling)
* Global includes (Javascript / CSS)
{% hint style="info" %}
To activate this function, please add the [ENV Variable](https://github.com/Flowerappeng-org/openflower/tree/main/deploy/docker#configuration): **COMMON\_WORKSPACE\_MODE**=SAAS
{% endhint %}
{% hint style="info" %}
From Version 2.3.3, you can add the [ENV Variable](https://github.com/Flowerappeng-org/openflower/tree/main/deploy/docker#configuration) **LOWCODER\_CREATE\_WORKSPACE\_ON\_SIGNUP** to control the behavior of your users (Member role) on self-hosted installation.\
\
true - members can use their own workspace when they sign up.\
false - members will not have their own workspace when they sign up.
{% endhint %}
{% hint style="warning" %}
If you want to close the possibility that anyone can Sign in and create an account, you can set the ENV Variable **LOWCODER\_EMAIL\_SIGNUP\_ENABLED** to "false".\
\
The Sign In / Sign Up Screen will still be shown, but the Sign Up will return an Error message and new users cannot create Accounts.\
\
This can be helpful if you have your own Identity / OAuth Provider listed and want to be sure that users only with these Identity / OAuth Providers can create Accounts on your OpenFlower installation.
{% endhint %}
The Workspace is a tool to use for organizing groups or user access to Apps. It is also used to apply a theme to a set of Apps.
A list of Workspaces
In the public OpenFlower Cloud, the amount of Workspaces is limited to 10.
In the upper right corner, at the profile, you can find the possibility to switch between your Workspaces.
Switch between Workspaces
### Apps & App Folders
In OpenFlower, you can create Apps. Each App represents what you can create on a single Screen. Often, a complete application consists of multiple Apps. You can then organize these relationships in App Folders or separate them by Workspaces.
Organize Apps into Folders to create order and show relationships
### Themes
You can create multiple [Themes](/build-applications/themes-and-styling) for your apps and select a style theme for each app individually. However, each Workspace has its own collection of Themes.
Themes helps to style Applications individually
### Global Includes
It is possible to include global CSS styles to fine-tune the visuals of Apps. Also, it may be necessary to include a Javascript script, which is executed for all Apps of a Workspace. With the help of global includes, you can achieve Workspace.
### Further administrative Settings
On self-hosted installations, you can set up thresholds for workspaces with the help of [ENV Variables](https://github.com/Flowerappeng-org/openflower/tree/main/deploy/docker#configuration)
* **LOWCODER\_MAX\_ORGS\_PER\_USER**
* Sets the default maximum number of Workspaces that a single user (as Admin) can create. This limit ensures that users can manage a reasonable number of organizations without overwhelming your installation.
* **Default Value**: 100
* **LOWCODER\_MAX\_MEMBERS\_PER\_ORG**
* Defines the default maximum number of members (including users and roles) allowed in a single Workspace.
* **Default Value**: 1000
* **LOWCODER\_MAX\_GROUPS\_PER\_ORG**
* **Description**: Specifies the default maximum number of groups that can be created within a Workspace. Groups are used for organizing members with similar roles or access levels, and this limit helps in keeping the group structure manageable.
* **Default Value**: 100
* **LOWCODER\_MAX\_APPS\_PER\_ORG**
* **Description**: Determines the default maximum number of applications that could be developed or maintained in a Workspace.
* **Default Value**: 1000
* **LOWCODER\_MAX\_DEVELOPERS**
* **Description**: Sets the default maximum number of Users with Developer-Role that can be registered in the Workspace.
* **Default Value**: 100
# Members and Groups
In OpenFlower, you can organize the members of your workspace using different groups, and assign roles to groups to manage [permissions for resources](/workspaces-and-teamwork/permissions-for-resources). You can find members and groups settings in **Settings** on the OpenFlower Admin Page.
## Roles
There are the following Roles for Users in OpenFlower:
### For Workspaces
* Admin
* Member
User Roles in Worspaces
### For Apps
* Owner
* Editor
* Viewer
User Roles for Apps
### For Datasources
* User
* Owner
User Roles for Datasources
A User in OpenFlower is an admin for his own Workspace when registered without an invite link. However, each user can be a member of one or multiple Worspaces.
In OpenFlower, you can organize the members of your workspace using different groups, and assign roles to groups to manage permissions for resources. You can find members and groups settings in **Settings** on OpenFlower Admin Page.
## Workspace members
In the **Members** tab, there are two pre-built groups by default. This helps you fast to differentiate between your colleagues who you want to invite to develop Apps together and everyone else - including the Users of these Apps. The predefined Usergroups are:
* All Members
* Developer
Independent from these Usergroups you can define your own Usergroups to manage permissions and keep the overview of everyone who is registered and using Apps in your Workspaces.
### Invite new members
You can invite members to your workspace by managing **All Members** group. Open the group and click **Invite Members**, then you can copy the invitation link.
You can also find the shortcut to **Invite members** on the bottom left of the OpenFlower Admin Page.
{% hint style="info" %}
Permission to invite new members to a Workspace is restricted to workspace **admins** and **developers group**.
{% endhint %}
### Workspace roles and permissions
Role
Workspace and group level permissions
Admin
Workspace
Modify workspace information (name, logo, etc.)
Delete workspace
Manage workspace members and set their roles
View workspace members
Groups
Create groups
Delete groups
Manage group members and set their roles
Member
None
Note that the workspace creator is automatically granted admin permissions.
## User Groups
Group-based management helps to organize members from different functional departments in your workspace. You can create User Groups in the **Members** tab.
### The default Group "Developers"
OpenFlower creates a **Developers** group by default which cannot be deleted, and workspace admins can add members to it. The members of the Developers Group can create new resources including apps, modules, navigations, folders, and data sources, and can manage the query library. Workspace admins can add members to the Developers Group.
### The default Group "All members"
To overview all Members of a Workspace, the default User Group "All members" can get used. Here, all Members of a Workspace regardless of their role or connection to other User Groups are listed.
### Own User Groups
In the **Members** tab, workspace admins can click **+ Create Group** to add a new group. The group creator automatically will be the group admin of the new User Group.
Group admins can add members to groups.
### Roles and permissions in own User Groups
The Administrator of a User Group can set an **Admin** or **Member** role for each group member. The permissions are listed in the table below.
Role
Permissions
Admin
Change group name
Delete groups
Manage group members and set their roles
View group members
Member
View group members
# Permissions for Resources
OpenFlower implements [Role-based Access Control](https://en.wikipedia.org/wiki/Role-based_access_control) (RBAC) by assigning a set of permissions to different roles. These permissions determine the actions users can take on resources, including apps, modules, navigations, folders, query library, and data sources.
Only workspace admins and members of **Developers** group are allowed to create resources. Workspace admins are in fact the owner of all resources.
## 1) Application Folders
Folders help you sort out the Apps, Modules, and Navigations in your Workspace. Only workspace **Admins** and members of **Developers** group have the following permissions for folders:
* Create
* Rename
* Delete
* Move Apps, Modules and Navigations into or out of folders
## 2) Apps, modules, **navigations**
The way permissions are applicable for Apps, Modules, and Navigations are the same.
Apps, Modules, and Navigations works the same way for permissions.
The owners of an App, a Module, or a Navigation can add members and assign different roles to them. To set Permissions for Users or Usergroups use the **Share** button in the App Editor at the top right, then click **Add members**.
Set Permissions based on Roles for an App
Choose members and / or groups from the list and set roles for them.
The available roles and their corresponding permissions are listed in the table below.
Role
Permissions
Viewer
View and use the app, module and navigation
Editor
View and use the app, module and navigation
Rename
Edit
Publish
Duplicate
Export
Owner
All permissions of Editor
Delete the app or module
Set roles for members
### Anonymous User Access for Apps
If you want to make an app or a module or a navigation public to all users (including anonymous users), you can toggle on **Make the app public** in **Share** settings.
Apps can be public viewable without OpenFlower Login
## 3) Data sources
Only workspace admins and developers can view the **Data Sources** page and create new data sources.
Overview of all Datasources of a Workspace
For each data source, workspace admins and the creator can change its **Access Control**. Go to OpenFlower homepage > **Data Sources**, and click `···` > **Access Control**.
Set Permissions based on Roles for an Datasource
In **Access Control** settings, add members or groups from the workspace, and then choose their roles (**Can use** or **Can manage**).
The permissions of these two roles are listed in the following table:
Role
Permissions
Can use
Use data source when editing an app/module/navigation/library query
Can manage
Use data source when editing an app/module/navigation/library query
Edit data source
Delete data source
Manage data source permission roles
## 4) Query library
Workspace Admins and members of Developers group can create Query Library in OpenFlower and have read, write, use, and delete permissions for queries (if they can use the query's corresponding data source).
# OAuth
Since OpenFlower 2.1.3 we support OAuth for 4 standard sources. The list will increase and be completed by a generic OAUTH configuration ability.
As for now we support:
* Google
* Github
* ORY
* KeyCloak
Next on the list are:
* Atlassian
* Gitlab
* Microsoft Graph (AD / B2C) as OAuth
* LinkedIn
* Facebook
### Use OAuth providers in 2 ways.
* By Invite Link
* By workspace welcome Page
### Invite Link
When an Admin or User with appropriate rights sends an Invite Link, then this Invite Link contains the information in which workspace the new users get invited. In this way, the List of OAuth Providers at the Sign in and Sign up Screens is adapted.
### Workspace welcome page
Based on a URL pattern you can guide new Users to your Workspace welcome page, where they will find the List of OAuth Providers at the Sign in and Sign up Screens too.
```
// URL pattern to show the Workspace welcome page
// The Workspace-ID == the Org ID.
https:///org//auth/login?redirectUrl=...
```
### Manage Login Methods (Auth Providers)
In the Admin area of OpenFlower select Settings > Auth Providers. Here you see the list of currently active auth providers. At the beginning, you will always see the standard-provider "Email"
{% hint style="warning" %}
In OpenFlower, Auth Providers except Email are bound to the Workspace. That means, that per workspace you can have individual settings and Auth Provider.
{% endhint %}
the list of Auth Providers per Workspace can be different -exept the Standard Provider Email
{% hint style="info" %}
As OAuth Providers are bound to a single Workspace, they will not appear on the general Sign In or Sign up screens, but only on the Workspace-related screens.
{% endhint %}
# KeyCloak
### KeyCloak as Identity Provider
To use KeyCloak as an Auth Provider, you must install and maintain an own installation of KeyCloak. A docker installation is fast achieved.
In KeyCloak you have to set up first a "Realm". This is a tenant within KeyCloak. Select (or create) your Realm with the top left corner menu.
In your Realm, you can then create and configure a Client. We show here the most minimal configuration to enable Sign in and Sign up with KeyCloak for OpenFlower.
### Setup a KeyCloak Client
Choose a name and id for your Client.
Make sure the "Standard Flow" is activated, as also "Client authentication" and "Authorization". Only when checked these options, KeyCloak will issue the needed Client-Secret.
Configure the OpenFlower redirect URLs.
{% hint style="info" %}
For the cloud, the "Valid redirect URI" is
{% endhint %}
After the setup, you can now look for the generated Client-Secret.
copy the Client Secret for the setup of KeyCloak as Auth Provioder in OpenFlower
Check the Settings to make sure the right capabilities are activated...
### KeyCloak as OpenFlower Auth Provider
in OpenFlower, go to Settings > OAuth Provider and select "KeyCloak" in the "Add OAuth Provider Dialogue"
Now you can enter all settings for KeyCloak
{% hint style="info" %}
Instance ID is the Base URL of your KeyCloak Installation
{% endhint %}
You can also change settings later.
{% hint style="warning" %}
The minimal scope to setup is "offline\_access openid".
{% endhint %}
Thats it! Now you can use KeyCloak to offer your Users to Sign in and Sign up with KeyCloak.
# Google
### Google as OAuth Identity Provider
To use Google as Auth Provider, you must setup a so-called "OAuth 2.0 Client ID". You can do so in the Google Cloud Console.
You can create many OAuth 2.0 Client IDs
Use the Form to create your Client ID (app registration)
You can set multiple redirect URLs
On the right side, you will find the Client-ID and Client Secret. Now you go back to OpenFlower Settings > Auth Providers and click "Add OAuth Provider" and select Google from the list of Auth Providers.
select Google as Auth Provider from the List
You can now copy and paste the Client ID and Client Secret from the Google Cloud Console.
Thats it! Now you can invite new Users to OpenFlower. They can choose Google to Sign Up (register) or Sign in / log in.
Based on an invite Link, users can now login with the OAuth provider Google.
# GitHub
### GitHub as OAuth Identity Provider
To use GitHub as Auth Provider, you must setup a so-called "OAuth App". You can do so in your Github Profile > Settings
On GitHub the creation of an OAuth Client Registration is comparatively simple.
GitHub Client Registration Settings
After configuring the Callback URLs, you can "Generate a new client secret".
{% hint style="warning" %}
Make sure you copy the client secret directly, as it is displayed only once. Later you cannot copy it again.
{% endhint %}
Now you go back to OpenFlower Settings > Auth Providers and click "Add OAuth Provider" and select GitHub from the list of Auth Providers.
You can copy and paste now the Client ID and Client Secret from the GitHub Client App Registration.
Thats it! Now you can invite new Users to OpenFlower. They can choose GitHub to Sign Up (register) or Sign in / log in.
When users chose to Sign in or Sign up with GitHub, they will get redirected to the GitHub Login page of the registered Client App
Here they have to Authorize your registered Client App to act and impersonate your users.
# Generic OAuth Provider
Since OpenFlower v2.4.0, a generic OAuth Provider has been introduced. The goal is to cover as many OAuth providers as possible without special implementation but give you, as an Admin, the freedom to connect to any OAuth Provider using a flexible configuration.
{% hint style="info" %}
As communicated and voted by the community, we introduced the functionality in v2.4.0 but are still optimizing it, based on your feedback. Latest by OpenFlower v2.5.x this function is stable. (We expect anyhow already before that version a stable function of it.)
{% endhint %}
OAuth Providers are configured individually per Workspace.
The configuration has three parts:
* Meta-Data
* OAuth Provider Configuration
* Information Mapping
### Setup a generic OAuth provider
As the Admin of your Workspace, go to Settings > User Authentication. Here, you will find a List of your configured User Authentication Providers.
Overview of configured Aouth Providers for your Workspace
Now, you can use the button in the upper right corner to add a new OAuth Provider. Select "Generic".
### .well\_known URI
The `.well-known/openid-configuration` URI is specifically part of the OpenID Connect (OIDC) standard. If a provider supports OpenID Connect, this endpoint provides a JSON document with the configuration details for OAuth and OIDC operations. OpenFlower will try to use this configuration data and will fill out the standard OAuth Provider Configuration fields as well as possible in the next screens of the Generic OAuth Provider Configurator.
Enter your Well Known URI to auto-fill the configuration in Step 2
### Popular Services
Here are some popular services and their OpenID configuration Endpoints
#### Google
```
https://accounts.google.com/.well-known/openid-configuration
```
#### Facebook
```
https://www.facebook.com/.well-known/openid-configuration
```
#### Microsoft
```
https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration
```
#### LinkedIn
```
https://www.linkedin.com/oauth/.well-known/openid-configuration
```
#### Apple
```
https://appleid.apple.com/.well-known/openid-configuration
```
#### Amazon Cognito
```
https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/openid-configuration
```
#### Salesforce
```
https://login.salesforce.com/.well-known/openid-configuration
```
#### Dropbox
```
https://www.dropbox.com/.well-known/openid-configuration
```
#### PayPal
```
https://www.paypal.com/.well-known/openid-configuration
```
#### Slack
```
https://slack.com/.well-known/openid-configuration
```
### Popular IDMs that you can self-host
#### Keycloak
```
https://{yourKeycloakDomain}/auth/realms/{yourRealm}/.well-known/openid-configuration
```
#### Okta
```
// Self-Host
https://{yourOktaDomain}/.well-known/openid-configuration
// Cloud (domain depends on the region)
https://{yourApp}.okta-emea.com/.well-known/openid-configuration
```
#### Auth0
```
// Self-Host
https://{yourAuth0Domain}/.well-known/openid-configuration
// Cloud
https://{yourApp}.auth0.com/.well-known/openid-configuration
```
#### Ory
```
// Self-Host
https://{yourOryHydraDomain}/.well-known/openid-configuration
// Cloud
https://{yourApp}.projects.oryapis.com/.well-known/openid-configuration
```
#### Authentik
```
https://{yourAuthentikDomain}/application/o/.well-known/openid-configuration
```
#### IBM Security Access Manager (ISAM)
```
https://{yourISAMDomain}/mga/sps/oauth/oauth20/.well-known/openid-configuration
```
### OAuth Source Meta-Data
Meta Data describes the Auth Source, allowing you to influence the visual representation of the OAuth Provider in the Sign In / Sign Up screen.
Enter a Displayed Name, Category, Icon and a Description
{% hint style="danger" %}
In OpenFlower v2.4.0 you must set the field "Source" to GENERIC
{% endhint %}
From OpenFlower v2.4.1, the field "Source" will be hidden and filled out automatically.
### OAuth Configuration
In Step 2, you can now set up the configuration Data for your OAuth Provider. We introduced this in v2.4.0, and the screen will surely be extended with features in the upcoming versions.
{% hint style="danger" %}
Scopes must be set with a space character between the scopes, not comma-separated.
{% endhint %}
{% hint style="info" %}
Some providers do only support OAuth - but not (yet?) OpenID. This means that the User Introspection Endpoints /userinfo are not available. For this case you can activate or deactivate this Introspection. (This function comes into effect at OpenFlower v2.4.1)
{% endhint %}
### Provider-Side Configuration
At your IDM you would need to prepare an OAuth Client resp. a OAuth Client Application. There are multiple settings.
* Redirect URL. Here you enter your domain of your installation like **** or ****
* Scopes: You should set the following Scopes if possible. **offline\_access** and **profile** are important.
* openid
* offline\_access
* email
* profile
* Supported OAuth2 flows: To handle User-Logins you need to activate the **Authorization Code Flow.** Also you may need to activate the **Refresh Token** possibility.
* Client authentication mechanism: Here, you can set **HTTP Body**
### OAuth Data Mapping
We introduce the possibility of mapping Data from OAuth providers to OpenFlower. We just started it in v2.4.0, and in this version, we enabled 4 attributes.
* UID (The User-ID in the IDM System)
* Email (The Email Address of the User in the IDM System)
* Username (The Name of the User)
* Avatar (The profile picture of the User)
OData Mapping
The second screen shows how the Avatar and Username come into effect after the Mapping.
{% hint style="warning" %}
In v2.4.0 we support mapping out of the JWT (access\_token) from the IDM. In future versions, we will also support the mapping of Attributes from the OpenID /userInfo endpoint.
{% endhint %}
{% hint style="info" %}
In future versions of OpenFlower, we will also support Attribute Matching of Token Claims to User Groups and Roles.
{% endhint %}
# Query library
The **Query Library** lets you store, reuse and share Data Queries for all Data Sources in a workspace. You can create and run queries in the Query Library, and call them from any OpenFlower app. This helps you to organize and pre-define important queries for colleagues that work with you on Apps for example.
The main function of the Query Library is to create and manage reusable Queries with Versioning.
## 1) Create a new query
1. Click **+ New** and select a data source. You can rename the query on demand.
Overview of Data Queries and Action Buttons to create new Data Queries
Write code and click ▶ **Run** to get results. The results will display in the bottom pane of the window.
You can create Data Queries for example as SQL Script for Databases
If available based on the Datasource, helping Metadata will get displayed on the right side to create Queries faster.
### Input parameters
There are cases where you want to pass dynamic parameters to a query. OpenFlower supports that by introducing input configuration of a query.
Click **Add** in the **Inputs** tab in the right upper pane to add input parameters.
With the template notation `{{}}`, you can use the dynamic Input parameters in the Query. To test the Input Parameter, you can set test values that are directly used in the Query.
Using Input Parameters for dynamic Queries.
{% hint style="warning" %}
You can only reference variables instead of writing JavaScript code in `{{}}`.
{% endhint %}
To edit the name and description of the input variables, click `...` and select **Edit** or directly click the title of the variable.
## 2) Publish Queries
When you finish writing a version of the query, you can publish it. Click `···` > **Publish**.
Queries need to get published to be usable in Apps
### History versions of Queries
To view and restore the history versions of a Query, go to `···` > **History version**.
You can restore your current draft to a history version by selecting the target version from the history version list and clicking **Restore this version**. Click **Exit** to return to edit mode.
### Version management of Data Queries
Queries may be updated on demand. You can make an adjustment to a query to a newer version and at the same time maintain the older version. Such version management is achievable in the query library. Click `···` in the top right corner to publish different versions of queries, and you can view and restore history versions.
The Query Library automatically suggests an Up-Versioning Format to choose from, (Minor to Major Version Change) so you can use [semantic versioning](https://semver.org/) (also known as SemVer) to name your version.
Semantiv Versioning to Data Queries
## 3) Using Data Queries from Query Library
In an app or module, Click **+ New** in the **Query editor** in the bottom pane, then select **Import from Query Library**.
Select a query from the library from the dropdown list, choose your desired version and pass in the corresponding input parameters.
## 4) Export and Import of Queries
### Export of Data Queries
You can export a Query as a JSON Definition file. This helps to use a Query across different Lowcocer installations for example, or simply as a Backup.
{% hint style="info" %}
Be aware, that the connected Datasource of a Query may have different security credentials at different installation locations.
{% endhint %}
With "Export to JSON" you can backup a query or store it externally to use it in other OpenFlower Installations.
### Import Queries
Based on the JSON Definition file, you can import Queries into OpenFlower. On the Query Library Overview Screen, you can use the Button "Import from File"
Import Data Queries from a JSON Definition File.
## Permissions
Workspace **Admin** and members of **Developers** group have access to the **Query Library** and have read and write permissions to all queries in the library.
# OpenFlower Marketplace
The OpenFlower Application Marketplace is a platform where the OpenFlower Community comes together to share and explore applications and modules.
It's the spot for app developers and business people to find innovative solutions in OpenFlower that can help streamline operations and enhance project outcomes. Here, users can contribute their own creations, tapping into a pool of shared knowledge and resources.
For us It's all about harnessing the power of collaboration to bring the best out of the OpenFlower platform, making it easier for everyone to achieve their goals with speed of light.
## Global and Local App Marketplace
The place where Apps are built and shared on the Marketplace of [prod-us1.openflower.org](https://prod-us1.openflower.org), we call the "global Marketplace".
If you operate a self-hosted installation you will be able to see and use the Apps from the global Marketplace always. However, you can share apps in a local Marketplace too, which is only available across all workspaces of your self-hosted installation.
In self-hosted installations, both Marketplaces are available and show the apps that are shared on these Marketplaces.
## Use Apps from Marketplace
{% embed url="" %}
## Publish Apps to Marketplace
{% embed url="" %}
{% hint style="info" %}
If you publish your App in the OpenFlower Editor on [prod-us1.openflower.org](https://prod-us1.openflower.org), your App will be listed on the "global Marketplace" and every OpenFlower User can see and use the App.
{% endhint %}
{% hint style="warning" %}
If you publish your App in the OpenFlower Editor on your self-hosted Installation, only Users inside your self-hosted Installation can see and use these Apps.
{% endhint %}
## Adding Title, Description, Category and Icon
In the left App-Settings Menu, you can add Title, Description, Category, and an Icon to your App, so the display on the Marketplace is informative.
{% embed url="" %}
## Before you publish your App to the Marketplace
#### 1. Audit Your Application for Sensitive Data
* **Review Local Data Sources**: Examine all local data sources within your application to identify any that contain sensitive information. This includes user information, API keys, passwords, and any other data that should not be publicly accessible.
* **Check Local Data Queries**: Look through your local data queries to ensure they do not reference or pull in sensitive data inadvertently.
#### 2. Remove or Anonymize Sensitive Data
* **Anonymize Data**: If your application requires example data to demonstrate functionality, replace real data with anonymized or fictional data that does not relate to any real individuals or entities.
#### 3. Replace Local Data Queries and Sources with Neutral Equivalents
* **Implement Neutral Data Queries**: Replace queries that access sensitive data with neutral data queries. These should demonstrate the app's functionality without using or exposing real data.
* **Use Neutral Data Sources**: Switch out any local data sources containing sensitive information with neutral, example-based sources. Ensure these sources clearly illustrate how the app operates without relying on real data. Remove any Data Source from your application, which uses Passwords or other Backend Side encrypted credencials. This includes development environment configurations that might contain API keys or database credentials. You can use anonymous accessible APIs or place Demo-Data in [Temporary States](/business-logic-in-apps/write-javascript/temporary-state) and bind queries to these Temporary States for demonstration purposes.
#### 4. Place a documentation in the app
To help others to use your app, you can use a Text-Display component with Markdown at the bottom and write a README, so other users understand how to use the App and its components & logic.
# Create a new App
## App or Module?
A [Module](/build-applications/create-a-new-app/modules) is a special type of App, which can be **re-used** inside of other Modules or Apps and especially it is possible to [embed](/publish-apps/embedd-an-app) the Module directly in your native Web-Application outside of OpenFlower.
The Editor for Apps and Modules is the same, only Modules have some extra settings and parameters regarding the embedding.
If you would like to [embed](/publish-apps/embedd-an-app) or re-use your Application, choose "Module". If you want only to build a fullscreen Application and eventually hang it in a Navigation, use "App".
{% hint style="info" %}
Be aware that nested Modules "in each other" can cause a slowdown of the Application. It is always a consideration of listed elements in terms of the re-usability of child components or faster Application behavior. When creating Modules, testing regarding the speed of the overall Application and consumption of resources is necessary.
{% endhint %}
## Create a new Application or Module
Click **New > App** (or **Module**) on the upper right of OpenFlower Admin Page. The App or Module will get created and the view switches automatically to the App Editor.
Only workspace **admins** and members of **Developers** group can create apps.
Creat Applications with the upper right button.
You can rename the App at the left-top of the App editor.
Renaming an App with the top left Menu
## Export and import an app
### Export an app
Apps can get exported to a JSON Definition file at multiple places. For example, click your app name and select **Export to JSON**, the app will be exported to a JSON file.
### Import an app
You can import an existing app in a JSON format by clicking **New > Import**.
# Modules
One of the most **powerful concepts of OpenFlower** is **Modules**. OpenFlower Modules are Applications, that can get **included and repeated** in other Applications. You can insert a module into an app or other modules (referred to as *external apps* in the rest of this document) and it **functions just like a single component**. Also, Modules can get [**integrated/embedded natively in other Web Applications**](/publish-apps/embedd-an-app)**!**
When building an app, you want to reuse a bundle of components and queries across different apps. Imagine a User-Profile Card. Profile-Image, Name, Contacts. If you create these Elements inside of a Module, you can integrate this in all other Apps as it would be a single component.
## Module basics
### Create a new module
Select **New > Module** at the top right of the Admin Page to enter the module editor.
Create a new Module like a normal App
### Editing of Layout, Components, and Data Queries
There are no differences in editing a Module or App other than the Module Settings. Placement of Components and Dataqueries behaves the same as in the App Editor. You can insert components and create queries the same way as your normal App-building process.
In the Module Editor, you can resize a module by dragging the bottom-right corner to the desirable default size. Be aware, that the screen in the editor does not show the real horizontal size of the module, as this size is defined at the App, where the Module is placed.
{% hint style="info" %}
Any changes you made at Modules are only available and active for Apps that use the Module after the new publishing of the Module!
{% endhint %}
Modules get created and edited as normal Apps.
Toggle the button in the **Properties** panel to control whether the **component height scales with the container**. This only works for the fixed-height components within the module.
### Insert module to apps or other modules
When editing an App or Module, select **Insert > Extensions > Modules** to display the modules that you have access to.
You can select available modules in the Extension Panel
Then drag and drop the module onto the canvas, set input parameters, and change styles inside the module's **Properties** panel.
Modules are placed liko other Components too
The horizontal size is free to choose from. However, the Module inside considers the bounding box size as 100% of its horizontal size.
The Module Width scales by the placement in the App
### Module settings
As modules can get embedded, they need to be able to interact with outside apps or websites. There are four elements to support communication with a Module.
* **Inputs**: dynamic parameters passed into the current module from external apps.
* **Outputs**: set data exposed to external apps.
* **Methods**: methods exposed to external apps. For example, you can define a module with a `resetTitle` method, so that external apps can call it to reset the module's title.
* **Events**: module events can be handled by external apps. For example, you can define an event named `dataChanged`, so that external apps can add event handlers to it once the `dataChanged` event is fired by the module.
Modules have Settings & possibility to test these - to communicate with the outside App or Website.
## Module settings
### Input
Module inputs are parameters passed to the module from external Apps. The supported input types are **data**, **string**, **number**, **array**, **boolean**, and **query**. The first five are data types. Choose **data** to not restrict it to a specific data type. When choosing the type of **query**, you can pass in a query from external apps and trigger it inside the module. Then you can reference a module input parameter by its **name**.
#### Add a new Input
In the **Settings** tab (green), click **+** **Add** to create a new **input**. Click the input to rename it and select a data type.
#### Input Test
To quickly test the effectiveness of Input parameters during editing a Module, you can use the **Input Test** function. In the **Module Editor**, select the whole Module to conduct tests with simulated input data in the **Properties** panel of the Module (blue).
Modules can receive dynamically input data
{% hint style="info" %}
Make sure, that you remove any test data when you publish the Module.
{% endhint %}
### Output
Module outputs are the data exposed to an app or other modules. You can inspect the outputs of a module in the data browser and access them via JavaScript code in `{{ }}`. Then you can check out and reference the outputs of a module in apps or other modules using it.
{% hint style="info" %}
We suggest to chose output data names carefully.
* Make sure they express the module origin
* Make sure they express the inner source (from data, from action etc.)
{% endhint %}
### Method
Methods are used to call functions / action in a Module from outside - your App or Webpage where you embed a Module.
#### Add a new Method
In the **Settings** tab, click **+** **Add** to create a new Module Method. Click the Method to rename it and select an action.
From an App, one can call Methods of a embedded Module.
{% hint style="warning" %}
When creating a Method for a Module, you cannot create input parameters for the Method and can only reference parameters within the scope of the current Module.
{% endhint %}
#### Call a Method
When using modules, you can call a module method in two ways:
* In event handlers, select **Action** > **Control component**, and then select the **component** and **method**.
* Use dot notation in JavaScript queries. For example, `module1.clearAll()` calls the method `clearAll()` of `module1`.
In the App, Methods of an embedded Module are accessible like for other Components.
#### Method Test
You can simulate testing method calling in the **Method Test** function.
### Event
Events are used to transfer signals from a module to external apps, such as defining `orderPlaced` `OrderModified` events for an order management module. You can add and fire events within a module, and deal with them using [Event Handlers](#event-handlers) externally.
#### Add a new event
In the **Settings** tab, click **+** **Add** to create a new module event. Click the event to set its name.
#### Trigger an event
In the following example, the event `contentChange` is triggered when the content in any input box changes. You can trigger it in two ways:
* In **Event handlers** of both input components, click **+ Add**, select **Change** as the component event and **Trigger module event** as the action, and finally select the module event `contentChange`.
* Use dot notation in JavaScript queries: `contentChange.trigger()`.
#### Event handlers
When an app uses a module, you can configure how the current app reacts to the module's events. For example, in **Event handlers** of `module1`, click **+ Add**, and select the module event `contentChange`and the action **Show notification**.
#### Event Test
The following example conducts event tests in the **Event Test** section.
## Permissions
End users are automatically granted permission to view modules in apps or other modules they have viewing permissions with. If you are an editor and wish to use a module in external apps, you should at least have the viewer's role of that module.
## Releases and versions
OpenFlower stores the historical versions of your modules for your reference. Click **Preview > Publish** at the top right. The release management of a module is identical to that of an app. For detailed information, see [version history](/build-applications/create-a-new-app/version-and-release-management).
{% hint style="info" %}
For an unpublished module, the apps and modules use its latest version; while for a published one, you need to publish it again to sync your latest changes.
{% endhint %}
# Version and Release Management
Version and release management aims at providing a stable live version for end users and allows you to build and test your app safely.
By default, end users interact with the latest version of your app. After drafting and modifying your ideas, you can preview and compare with different history versions, and finally publish the version that meets all your needs. The newly published version now becomes live, and all your future updates will not affect the live version until you publish again.
## History versions
OpenFlower automatically stores all your history changes during the construction of an app, such as the addition or deletion of the components, adjustment of the property of the components, rearrangement of the layout, and update of a custom function. You can use it to refer to your earlier ideas or revert to a previous version.
App history versions are only accessible to editors and admins.
### View a history version
You can view any version of your previous drafts. Click **Preview** **>** **History**.
### Restore a history version
You can restore your current draft to a history version.
1. Select the target version from the history version list
2. Click **Restore this version** on the topbar
## Release management
Apps are usually upgraded on a regular basis to include new features, improve business processes, and correct failures. However, the development of a new version of an app takes time and you need to ensure that user experience is not affected during this progress.
By default, end users interact with the latest version of your app. Once you finalize the sketch for a newer version of your app, you can proceed to publish it. Click **Preview > Publish**.
Now the newly released version becomes live for all end users, and all your future updates will not affect the live version until you publish again.
# App Editor
In OpenFlower, the Application Designer is where you assemble components, create queries to interact with data, and publish your apps. It consists of five areas:
1. Toolbar on top
2. Canvas (yellow)
3. Data browser (blue)
4. Query editor (green)
5. Component and property pane (red)
The standard view of the App Editor
The left pane is switchable, so you can view the Data browser or App-wide settings for layout and page includes (Javascript and CSS). You can:
* Set Canvas size
* [Set App Theme](/build-applications/themes-and-styling)
* Manage included JavaScripts and CSS style
The right pane is switchable too and offers the searchable list of all Components that can get placed in your App. In the "properties Mode" you can see all customization details for the currently selected Component on the Canvas.
The Details / Settings Panels of the App Editor Screen
## Toolbar
The Toolbar is made up of a top bar and a left sidebar.
On the top bar, you can:
* Change the App name
* Export to a JSON file
* Control the visibility of the left and right panes as also the query editor (middle)
* Share your App
* Preview and deploy your App
* Check the history versions on an App
On the left sidebar, you can:
* Show or hide the **Data Browser**
* Start tutorial for application designer
## Canvas
The canvas (yellow) at the center of the editor is where you design and see the overall UI. Drag and drop components onto the canvas. You can imagine it like a blank page at the beginning.
The canvas has an automatic, magnetic Grid system. Components will visually always snap to the nearest left and top grid line. This allows a fast but ordered layout of the Application.
You can influence the background color as also the horizontal amount of grid cells in the [theme](/build-applications/themes-and-styling).
## Data Browser
The data browser (blue) on the left pane contains **Queries**, **Components,** and **Globals** sections. Here you can inspect the data in a tree structure in real-time. For example, to check the returned data of a specific query or component, find its node in the belonging section and click to expand.
## Query editor
The query editor (green) is at the bottom and consists of two sections: query list (with **Queries** and **Metadata** tabs) on the left, and query settings ( with **General**, **Notification,** and **Advanced** tabs) on the right. Create queries to interact with data sources here.
Queries link data sources to your apps and perform CRUD (create, read, update, and delete) operations on data sources.
The query editor is flexible and adapts the options to build queries to the data source. You can compare SQL Database and OpenAPI queries for example.
## Component and property pane
The component and property pane (red) is located on the right of the window. Drag components onto the canvas from the **Insert** tab and edit the properties of the components in the **Properties** tab.
When a component is selected on the canvas, the **Properties** tab will be activated automatically and display the properties of that component.
# Visual Components
With Version 2.0.0 of OpenFlower there are 56 Components.
These components share a number of [common settings and configurations](/build-applications/app-editor/visual-components/common-component-settings).
### Data visualization Components
# Common Component Settings
The visual Components of OpenFlower share some general Settings and Configurations. You may find nevertheless Components, for which these or that Setting may not apply - and so it's not shown in the Application Editor.
Click on any Component opens the Properties panel to show all Settings & Configurations.
### Component Name
The component Name is important as it is the same time the identifier to address a visual Component via Javascript or in any dynamic way.
{% hint style="info" %}
It makes sense to decide in general between [Snake- and Camel-Case](https://www.freecodecamp.org/news/snake-case-vs-camel-case-vs-pascal-case-vs-kebab-case-whats-the-difference/). Kebab case is not suggested, as the "-" between words can be interpreted in Javascript as minus-operation in edge cases.
{% endhint %}
Make sure you give every component a self-speaking name
The component name is a selector for example in ui based Event handlers
Also in Javascript you use the same name to address the Object, its Attributes and Functions.
### Label
Many Components have the possibility to show Labels for the user, so it is clealy communicated what for example an input field is meant for.
Labels helps the users of Apps to understand interaction.
#### Orientation
Labels can have different orientations.
Labels can be oriented left or top of a component. The text itself can additionally be oriented left-side or right side.
#### Tooltip
Additionally it can be helpful for users to use Tooltips for descriptions and suggestions.
#### Internationalization
Based on the language information of the browser, one can translate text in OpenFlower on the fly.
get the User-Language from the Browser
For Labels and Tooltips, a [Handlebar Javascript expression](/build-applications/app-editor/data-selection-and-javascript) can get used to reading from a translation register (JSON).
```javascript
// reading the User Language from Browser
{{navigator.language || navigator.userLanguage}}
```
```json
// a Translation Register as JSON
{
"product_price": [{
"en-US": "Price"
}, {
"de-DE": "Preis"
}, {
"fr-FR": "Prix"
}],
"product_name": [{
"en-US": "Product Name"
}, {
"de-DE": "Produktname"
}, {
"fr-FR": "Nom de produit"
}]
}
```
Use a Translation Register as JSON
```
// dynamically reading from the Translation Register JSON for the label
{{translations.value.product_price.find(item => item.hasOwnProperty(userLanguage.value))[userLanguage.value]}}
```
### Layout
The Layout Settings section can display different settings, based on the selected Component. I most of the cases here you find Settings for the placement of a Component.
* Orientation (left center right justify) (where applicable)
* Vertical space (fixed, automatic) (where applicable)
* Prefix and Suffix Icons (where applicable)
### Disable & hide
Most of the Components can be hidden and/or disabled dynamically by a [Handlebar Javascript expression](/build-applications/app-editor/data-selection-and-javascript).
#### Disable Components
Many components can set in "disabled" State to not hide Components - but indicate that User cannot enter Data right now.
#### Hide Components
Nearly every Component can get "hidden and shown" dynamically. This is useful to switch dynamically between Application elements upon user input or interaction.
Components can get hidden by static or dynamic Setting
#### Vertical space of hidden Components
When Components are hidden, they do not consume vertical space. This is a special ability, which comes with a small challenge in the Application Editor. The advantage is, that multiple Components could get dynamically switched (shown or hidden), so you can dynamically react to user inputs or interactions.
hidden Components does not consume vertical space, but can get selected.
As soon as a Component is hidden, a "small closed eye icon" indicates this state in the App Editor. The component can still get dragged and selected. As soon as selected, it will show as long as selected its true height.
As soon as selected or dragged, a Component shows it height.
You can now place other components in the same vertical place as the hidden Component. This can lead to a small challenge in the App Editor to drag and place Components that overlap. It is suggested to work then with static true/false setting for the attribute "Hidden", so you can find the desired Component displayed with its height when you need it.
Components that are hidden can pe placed vertically at the same position.
{% hint style="info" %}
In OpenFlower v2.0.0 the fields "Hidden" and "Disabled" are unfortunately at different places in the Properties Panel across the components. We will fix and order this in a future version.
{% endhint %}
### Event handlers
One of the powerful concepts of OpenFlower are the Event handlers. Based on User interaction almost every Component can release Events, on which you can react with different actions.
For each components a set of possible User interaction Events is accessible
#### User Interaction Event Types
* Change (when user input data changes)
* Focus (when the user points to the component
* Blur (when the user left the Component)
* Submit (when the user submits a Form, where the Component belongs to)
* Click (when a button like Component is clicked)
* Open / Close (for collapsible Components)
* Switch Tab (for Tabbed containers)
{% hint style="info" %}
You can find a list of Event Handlers here: \[TODO list of event handlers)
{% endhint %}
When a Component supports User interaction Events, you can have one or multiple actions based on a single Event type or different Event types.
Each Component which supports Events can have multiple Handlers (Actions) for Event Types.
#### Actions for Events
Each Event handler has an Action out of a list of possible Actions. Each action has individual Settings.
* Run Query
* Control Component
* Run Javascript
* Set temporary State
* Go to App
* Show Notification
* Go to URL
* Copy to Clipboard
* Export Data
[More about the Event Handlers you can find here](/build-applications/app-interaction/event-handlers).
#### Order of Event Actions
{% hint style="info" %}
In a future version of OpenFlower, we will make sure it is possible to change the order of the Event Handlers. As for now, it is not possible and you would need to plan the order of Event Actions if your App needs multiple Event Handlers for a single Component.
{% endhint %}
### Style
Components support a variety of [Styling settings](/build-applications/themes-and-styling) like colors, borders, and backgrounds.
Different Components have different support for styleable Attributes
# File upload
File Upload Component
## Basics
The File upload helps you to able users to upload binary and text Files and process this data further in OpenFlower to send it to local or remote Storage and other Backends.
### File type
You can input an array of strings to restrict the types of the files to be uploaded. The default value of file type is empty, meaning that no limitation is pre-defined. Each string value in a specified file type array should be a [unique file type specifier](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#unique_file_type_specifiers) in one of the following formats.
* A valid case-insensitive filename extension, starting with a period character ("."), such as `.png`, `.txt`, and `.pdf`.
* A valid string in [MIME format](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) without an extension.
* String `audio/*` indicating "any audio file".
* String `video/*` indicating "any video file".
* String `image/*` indicating "any image file".
For example, when the value of file type is `[".pdf", ".mp4", "image/*"]`, you can upload PDF files, MP4 files, and any type of image files.
### Upload type
You can decide whether to upload a single file, multiple files, or a directory.
Configure the File Upload to accept individual, multiple Files or whole Folders
### Display uploaded files
Switch on or off **Show upload list** to display or hide the list of the uploaded files. You can also set this property via JS code. By default, its value is "true".
The upload list presents the file names of all uploaded files in chronological order. You can also access the name of the uploaded files via the property `files[index].name`. When hovering your mouse over a file, the 🗑️ icon appears and you can click it to delete the corresponding file.
### Parse files
Toggle **Parse files** and OpenFlower will try to parse the uploaded file data structure into objects, arrays, or strings. This does not work with binary data but with structured text data like Excel, JSON, and CSV files.
OpenFlower can try to parse the content of the files so you can directly access it.
You can access the parsed result via the property `parsedValue`.
For each uploaded file OpenFlower will try to parse and you can access the data of the files then in the array.
// access the structured content of an uploaded File in OpenFlower Apps
file1.parsedValue[0]
// the array contains the data for each uploaded file.
file1.parsedValue[0], file1.parsedValue[1], file1.parsedValue[2]
You can access the contents of Excel, CSV and JSON Files as JSON Data object after upload and parse
## Validation
Under the validation tab, you can configure how many files are allowed to be uploaded, as well as the minimum and maximum size of a single file to be uploaded.
You can define the minimal and maximal size of files that can get uploaded
### Max files
When the upload type is "Multiple" or "Directory", you can set **Max files** to limit the maximum number of files to upload. If the number of files to be uploaded exceeds this threshold, the latest uploaded files will replace the oldest ones.
If multiple files can get uploaded, you can define the maximal amount of files
### File size
You can set the minimum and maximum size of the files to upload, using KB, MB, GB, or TB units. The default unit for file size is byte. When the size of the uploaded file exceeds the limit, you will see a global alert.
### Access uploaded files
Files uploaded via the file upload component are stored in browser cache memory in **base64-encoded** string format. To store these files in data sources, you need to build queries to connect to databases or APIs. You can view the properties of the uploaded files in the data browser in the left pane, or access property names in `{{}}` or JS queries via JS code. Commonly used properties are as follows.
* `value`: A list of the content of the uploaded files, encoded in base64.
```
// Access the File content (represented as base64)
{{file1.value[0]}} // will return "WwogIHsKICAgICJpZCI6ICJkODE5NGI3Mi1lZGNiLTRhMWMtYTRlMC1lZT...
```
* `files`: A list of metadata of the uploaded files, including `uid`, `name`, `type`, `size`, and `lastModified`.
```
// Access the File metadata information.
{{file1.files[0].name}} // will return "open_issues.json"
{{file1.files[0].type}} // will return "application/json"
{{file1.files[0].type}} // will return "247285" (in bytes)
```
* `parsedValue`: A list of the value of the parsed files.
# Charts and graphs
Charts and graphs are visual representations of data that are used to simplify complex information and make it easier to understand. They can help highlight key insights and provide a quick summary of data that would otherwise be difficult to interpret. Charts and graphs come in different forms, such as bar graphs, line graphs, pie charts, scatter plots, and more, each suited for different types of data and analytical purposes.
OpenFlower allows you to insert multiple forms of charts and graphs into your apps to satisfy your needs in different use cases.
## UI mode
### Data format
In UI mode, the **Chart** component supports presenting data stored as an array of JS objects. Each object field corresponds to a column in tabular format. The objects in the following array contain three fields: `date`, `fruit`, and `count`.
```json
[
{ "date": "2022-03-01", "fruit": "apple", "count": 4 },
{ "date": "2022-03-01", "fruit": "banana", "count": 6 },
{ "date": "2022-04-01", "fruit": "grape", "count": 10 },
{ "date": "2022-04-01", "fruit": "apple", "count": 3 },
{ "date": "2022-04-01", "fruit": "banana", "count": 2 }
]
```
You can also use JS code in `{{}}` to reference data from other components or queries, or to transform data to meet specific needs.
For example, the query result of `query1` is as follows.
```json
{
"date": [
"2022-03-01",
"2022-03-01",
"2022-04-01",
"2022-04-01",
"2022-04-01"
],
"fruit": ["apple", "banana", "grape", "apple", "banana"],
"count": [4, 6, 10, 3, 2]
}
```
You can transform it using transformer `transformer1` with the following JS code.
```javascript
let dates = query1.data.date
let fruits = query1.data.fruit
let counts = query1.data.count
let result = []
for (let i = 0; i < dates.length; i++) {
result.push( {'date': dates[i], 'fruit': fruits[i], 'count': counts[i]} )
}
return result;
```
Then reference the value of the transformer `{{transformer1.value}}` as the data for the chart.
### Chart type
OpenFlower supports four types of charts: bar chart, line chart, scatter chart, and pie chart. You can select the chart type in **Properties** > **Data** > **Chart type**. You can also customize the layout and style of your chart in **Properties** tab.
### X-axis
Bar charts, line charts, and pie charts map values to categorical variables. Thus, in such charts, the X-axis usually shows non-numeric data—for example, date or department.
By default, OpenFlower automatically detects the X-axis data and its type. You can also manually select one among "Category axis", "Value axis", "Time axis", or "Log axis". For detailed information, see [X axis type](https://echarts.apache.org/en/option.html#xAxis.type).
### Chart series
In most types of charts, the **Chart series** (Y-axis) presents numeric values for the categories on X-axis. By default, OpenFlower populates all numeric fields to Y-axis. You can hide unnecessary fields in **Properties** > **Chart series**.
## Echarts JSON
Apart from the built-in charts and graphs, you can also plot your data with [Apache ECharts](https://echarts.apache.org/en/index.html), an open-source JS visualization library. You only need to complete the **Configuration** > **Option** field in JSON format. For detailed information, see [ECharts docs](https://echarts.apache.org/en/option.html#title) and [ECharts examples](https://echarts.apache.org/examples/en/index.html).
For an instance of using Echarts, see [Stacked Area Chart](https://github.com/Flowerappeng-org/openflower/blob/main/docs/build-applications/app-editor/visual-components/todo/README.md).
To style your charts, the [Theme Editor of ECharts](https://echarts.apache.org/en/theme-builder.html) is a good tool. It can export a JSON, which you also can use in the Workspace Themes section to style both Chart types. The native ones and the ECharts.
# Image
Use the **Image** component to present information in your apps in a vivic way. OpenFlower supports you adding an image via URL and base64 encoded data.
## URL
Drag the **Image** component onto the canvas or into a **Container**. Click the **Image** component, and the **Properties** tab is displayed on the right. You can set the URL to display an image.
## Base64 encoded data
You can also insert an image via base64 encoded data. Ensure that the encoded image source starts with `data:image/PICTURE_FORMAT;base64,` or simply`data:image;base64,`.
{% hint style="warning" %}
Don't miss the comma at the end of the prefix:
`data:image/PICTURE_FORMAT;base64`**`,`**`YOUR_BASE64_ENCODED_IMAGE_DATA`
`data:image;base64`**`,`**`YOUR_BASE64_ENCODED_IMAGE_DATA`
{% endhint %}
### Demo: upload and display an image
One common use case for base64 image display would be combining a **File Upload** component with an **Image** component.
Here is JS code that concatenates the prefix with the encoded base64 data of the uploaded file via `file1.value[0]`.
```javascript
{{"data:image/jpeg;base64," + file1.value[0]}}
```
## Set click preview for an image
Toggle **Support click preview** in the **Properties** tab to allow users to preview the image in its full size. Hover your mouse over the image, and you see **👁 Preview**. Then, you can click to preview.
## Set the style of an image
In **Properties** > **Style**, change border color and set **Border radius** in pixels or by percentage.
# Option lists
A drop menu ensures easy and error-free user input by offering a list of possible options. OpenFlower supports implementing option lists using components such as **Select** and **Multiselect**. You can configure an option list either manually or by mapping data from your data sources.
## Properties
Each option list has four properties.
* **Label**: the displayed text of the option to users
* **Value**: the unique identifier of the option
* **Disabled**: disable the option (the default value is `false`)
* **Hidden**: hide the option (the default value is `false`)
{% hint style="warning" %}
When more than one option in one list uses the same value, only the first option is valid and thus displayed.
{% endhint %}
## Manual mode
Under **Basic** > **Manual**, click **+ Add** to create a new option. Select an option to manually configure it. You can click `···` to **Duplicate** or **Delete** an option and drag `⋮⋮` to arrange its position.
Check the value of the selected option under **Components** in the data browser. For example, when **New York** is selected, you can find the string value `"1"` for **locationSelect**.
Manual mode is recommended for these scenarios:
* Manually manageable and enumerable.
* Used by only one component.
* Data doesn't come from data sources.
## Mapped mode
When you have option list data that comes from data sources, transformers or temporary state, you can use **Mapped Mode**. Under **Basic** > **Mapped**, input your data source array in **Data** box using JavaScript (JS) code. A list of options will be automatically mapped from this array. For example, access university information via `{{university.data}}`. Each item in the result array contains `country`, `web_pages`, `alpha_two_code`, and `name`.
You can reference the value of any filed of an option through `item` and its index `i`, starting from 0. In the following example, the **Label** of each option is the `name` of the university, the **Value** is the `web_page`, and those containing an opening parenthesis `(` in their names are disabled. The default value is set to the `web_pages` of the first item using `{{university.data[0].web_pages}}`. Note that the default value of an option list should be an element from the **Value** array but not the **Label** array.
Check the value of the selected option under **Components** in the data browser. For example, when "Ahi Evran University" is selected, its string value `[\"http://www.ahievran.edu.tr/\"]` is displayed.
# List View
The component **List View** displays rows of data. Similar to Form, Modal, and Drawer, it is also a container-like component that can hold other components or modules. For list viewing data, you first bind the data to a **List View** component and configure the naming rules for the items. Then, you design the display of the first row by dragging and dropping components, and this layout will be applied to all items within this component.
The following is a demo of **List View**, displaying part of BEST BOOKS OF 2021 from [Goodreads](https://www.goodreads.com/choiceawards/best-books-2021):
Drag and drop **List View** onto the canvas. Each item contains an **Image**, a **Text** and a **Rating** component. You can update the exhibition of the whole **List View** component by configuring the layout of the first entry.
Click the **Image** component, you see the defaulted image source.
The **List View** component retrieves data from a JSON array of objects and displays an **Image**, a **Text** and a **Rating** component for each entry. You can also pass query results to a **List View**.
## Bind data
The data of a **List View** component accepts two types of values: number and array.
* Number: Numbers are processed as row count and no valid data is passed into the **List View** component.
* Array: The length of an array is passed as row count and each entry in the array is processed as a JS object in JSON format, corresponding to a row in the **List View** component. For example, the following data contains two rows of data, each containing four fields: `rate`, `title`, `url`, and `cover`.
```json
[
{
"rate": "9.2",
"title": "The Shawshank Redemption",
"url": "https://www.imdb.com/title/tt0111161/",
"cover": "https://m.media-amazon.com/images/M/MV5BMDFkYTc0MGEtZmNhMC00ZDIzLWFmNTEtODM1ZmRlYWMwMWFmXkEyXkFqcGdeQXVyMTMxODk2OTU@._V1_UY67_CR0,0,45,67_AL_.jpg"
},
{
"rate": "9.2",
"title": "The Godfather",
"url": "https://www.imdb.com/title/tt0068646/",
"cover": "https://m.media-amazon.com/images/M/MV5BM2MyNjYxNmUtYTAwNi00MTYxLWJmNWYtYzZlODY3ZTk3OTFlXkEyXkFqcGdeQXVyNzkwMjQ5NzM@._V1_UY67_CR1,0,45,67_AL_.jpg"
}
]
```
You can view the detailed data about the **List View** component, its items, the properties, etc., in the data browser.
## Display data in inside components
After binding valid data to **List View** component and designing its inside components, you can add data to these components. **List View** supports local variables `currentItem` and `i`. Notice that you only need to change data of the first row, and the same settings are applied to the other rows automatically.
{% hint style="info" %}
You can bind a static URL address to the **Image** component for image display; and because that URL address is static, the same image shows up in all rows.
{% endhint %}
## Name items
You can set the item index names and item data names. This is useful when embedding a list in another list. For example, you can set the index of one list as `i`, and the inner nested `j` to avoid naming conflict.
### Item index name
By default, item index is named as`i`, referring to the index of list data and starting from zero. Besides using `i` as numbers, you can also use `i` to dynamically access data from query results.
For example, to access the `book_name` field from table `fiction` in the **Text** component, write the following code.
```javascript
{{getAllFictions.data[i].book_name}}
```
Then you can see the fiction book names displayed in **List View** by index order.
### Item data name
By default, you can reference the value of each item within a list using variable `currentItem`. For example, to display a serial number plus book name, write the following code in `text1` value.
```javascript
{{i+1}}. {{currentItem.book_name}}
```
{% hint style="info" %}
Circular dependency errors occur when you reference the data of a row by `listView.items[i]` from a component inside a **List View** component. It is recommended to use such reference only outside the list.
{% endhint %}
## Pagination
### Quick jumper
Toggle "Show quick jumper" or set its value to `true` to allow your users quickly jump to the specified page.
### Page size
You can configure whether to allow your users to customize how many items to be displayed on a single page by enabling or disabling the "Show size changer button" or set its value in JS. When disabled, you can set the default page size.
If enabled, you can configure several page sizes for your users to select.
### Total row count
By default, the total row count of a **List View** component is the number of current data items. You can also insert a value from a query. For example, `{{query1.data[0].count}}`.
## Reference List View items outside
**List View** supports exposing data of inside components with **Items** field. You can inspect the **Data Browser** in the left pane.
For example, drag an **Input** component into **List View**, and then you can reference the value of the **Rating** component in components outside the **List View** by the following code.
```javascript
{{listView1.items[0].rating1.value}}
```
# Drawer
In OpenFlower, **Drawer** is an overlay sidebar to display information or perform operations, without interrupting the workflow on the main window.
The following example builds a shopping cart using a drawer.
## Layout
When inserted by drag-and-drop operation, a **Drawer** floats on the right side (by default) of the main window. Then, you can add components onto the **Drawer** according to your needs. In the editing mode of a **Drawer**, other components on the canvas are not editable.
{% hint style="info" %}
When a drawer is closed, you can re-open it by clicking the corresponding label in the **Modals** tab in the left pane.
{% endhint %}
### Position
In the **Properties** tab, you can set the position of the drawer. The default position is the right side of the main window.
### Resize
In **Properties** tab, you can set the width of the drawer by pixels or percentage. Note that the height of a drawer is the same as the main window and is not customizable.
## Events
You can reference a drawer in JS code anywhere in your app or call it through a "control component" action in **Properties** > **Interaction** > **Event handlers**.
The following sections guide you through how to open and close a drawer by clicking a button in an online shopping app.
### Trigger openDrawer
Usually, in an app, you trigger opening a drawer by an event such as clicking a button. For example, in the [Online Shopping demo](https://github.com/Flowerappeng-org/openflower/blob/main/docs/build-applications/app-editor/visual-components/todo/README.md), opening a drawer to display the shopping cart is implemented in the following steps.
1. Add a button and rename it as `gotoCart`.
2. Set the event handler of the button. Select "Control component" as the **Action** and select the component "cart" and method "openDrawer". All these settings are auto-saved.
3. Click the button `gotoCart` and the binded drawer "cart" is open.
### Trigger closeDrawer
Triggerring "closeDrawer" is similar to triggering "openDrawer". When setting up the event handler, select the method "closeDrawer". For example, in the \[Online Shopping demo]todo), closing a drawer that displays the shopping cart is implemented in the following steps.
1. Add a button and rename it as `gobackShopping`.
2. Set the event handler of the button. Select "Control component" as the **Action** and select the component "cart" and method "closeDrawer". All these settings are auto-saved.
3. Click the "Continue Shopping" button and the binded drawer "cart" is closed.
# Google Maps
OpenFlower offers an innovative approach to integrating Geomaps from Google with an advanced geo-data-based overlay of eCharts, providing a dynamic and interactive mapping solution. This integration is particularly powerful for applications requiring real-time data visualization on geographical maps.
The core feature of this integration is the seamless combination of Google Geomaps with eCharts overlays. Google Geomaps provides a robust and familiar mapping interface, known for its detailed and accurate geographical data. By overlaying eCharts, OpenFlower enables the addition of rich, interactive data visualizations directly onto these maps. This overlay capability is not just about static data representation; it supports dynamic, real-time data updates, making it ideal for applications that require up-to-the-minute information, such as traffic monitoring, weather updates, or tracking movements in logistics.
Distribution of OpenFlower Users worldwide (10.2023)
OpenFlower ensures that the data displayed in the eCharts overlay is not only current but can also be updated in real-time with the [Stream Query](/connect-your-data/data-sources-in-openflower/websocket-datasource). This is crucial for scenarios where timely data is essential for decision-making. Users can see changes as they happen, providing an interactive and engaging experience.
The eCharts overlay on Google Geomaps in OpenFlower also offers a high degree of customization and interactivity. Users can zoom in and out, pan across different regions, and interact with the data points on the map. This interactivity is enhanced with tooltips, clickable elements, and various chart types like heatmaps, scatter plots, or line graphs, all geo-referenced and layered over the map.
### Using Geomap in OpenFlower
As the first step, place a new Chart from the right Components panel on the canvas.
Now you can select in the Component Properties the type "Map"
You can use the Properties "Zoomlevel, Longitude, and Latitude" to define the first impression of the GeoMap when the App is displayed.
In Version OpenFlower 2.1.x the eCharts Map is configurable like other eCharts by the "Options JSON"
{% hint style="info" %}
For more and deeper information check the eCharts documentation.
{% endhint %}
As eCharts is already integrated into OpenFlower, you only need to prepare and set the Options-JSON Data. The configuration follows the standard eCharts notation.
In the data section, you have nevertheless the possibility not only to set chart data but also the geo-point (lat, long), where the chart data should be displayed. Each Object in the data array will be one chart element on the map.
The section "encode" helps to tell the eCharts Map, which entry (array index number) of the data-array-element represents latitude, longitude, and the value to display.
```json
{
"tooltip": {
"trigger": "item"
},
"animation": true,
"series": [
{
"name": "Population",
"type": "scatter",
"coordinateSystem": "gmap",
"itemStyle": {
"color": "#00c1de"
},
"data": [
{
"name": "Azerbaijan",
"value": [
47.395,
40.43,
8352021
]
},
{
"name": "Albania",
"value": [
20.068,
41.143,
3153731
]
}, <...>
],
"encode": {
"value": 2,
"lng": 0,
"lat": 1
}
}
]
}
```
### Dynamic Data & Function binding
As in other components of OpenFlower, you can bind data and functions dynamically to the map.
```javascript
{
"tooltip": {
"trigger": "item"
},
"animation": true,
"series": [
{
"name": "Company Size",
"type": "scatter",
"coordinateSystem": "gmap",
"itemStyle": {
"color": "#9d4edd"
},
"data": {{mapData.value}},
"symbolSize" : {{function (val) {return window.mapValueToSize(val[2])}}},
"encode": {
"value": 2,
"lng": 0,
"lat": 1
}
}
]
}
```
In this case, the App-global function "mapValueToSize" is bound to the map settings, so the size of the Scatter Plot dots can be dynamically adjusted based on the "value" - of the mapped data.
### Setting Geo-Markers & JavaScript Access
In Version 2.1.x the possibility to place Geo-Markers on the map is possible via Javascript by accessing the maps object.
Here you can see the possibility to access the "gmap" object by the new function of the eChart Component "getMapInstance()". The gmap object is the well-known Google Maps Javascript Object, on which you can execute all typical operations.
```javascript
const renderMarker = async function () {
const gmap = await chart1.getMapInstance ();
var london = {lat: 51.5074, lng: -0.1278};
var marker = new google.maps.Marker({
position: london,
map: gmap,
title: 'Welcome to London!'
});
}
renderMarker ();
```
### Google Maps API Key
When you publish your app, an Google Maps API Key must be in place to display the App accordingly. Use to create your API Key.
To display only the Map and use the JavaScript API, "Map Embed API" and "Maps JavaScript API" need to be activated.
Now you can create and see your Google Maps API Key. It is suggested that you limit the Traffic by a Domain or IP Range.
# Table
The Standard Table is a highly functional and feature-rich component. It is recommended for Server-Side paging and filtering when data display for tables needs many individual settings.
The OpenFlower Table supports auto-size as a component as well as fixed size, where the Header and Toolbar can be fixed when the Table-Body is scrollable.
{% embed url="" %}
Header & Toolbar can be fixed
{% endembed %}
The Borders of Tables can be set individually for the whole table till down to the individual cell.
{% embed url="" %}
Individual Settings for Borders in Tables
{% endembed %}
{% embed url="" %}
Individual Grid Settings in the Table
{% endembed %}
Also, the Text Styles can be individualized for every column.
{% embed url="" %}
### Component Playground
todo
### Component Auto-Docs
{% embed url="" %}
### Properties of the Table
These properties are accessible in {{ }} notations, as well as in JavaScript Queries. \\
{% hint style="warning" %}
Properties are read-only
{% endhint %}
| Property Name | Type | Description |
| --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| selectedRow | Object | Provides Data for the Currently Selected Row, Indicating the Row That Triggers a Click Event If the User Clicks a Button/Link on the Row |
| selectedRows | Array | Useful in Multiple Selection Mode, Same as SelectedRow |
| selectedIndex | | Selected Index in Display Data |
| selectedIndexes | Array | Selected Index in Display Data |
| changeSet | Object | An Object Representing Changes to an Editable Table, Only Contains the Changed Cell. Rows Go First and Columns Go Second. |
| toUpdateRows | Array | An Array of Objects for Rows to Be Updated in Editable Tables. |
| pageNo | Number | Current Display Page, Starting from 1 |
| pageSize | Number | How Many Rows per Page |
| sortColumn | | The Name of the Currently Selected Sorted Column |
| sortDesc | Boolean | Whether the Current Row Is in Descending Order |
| pageOffset | Number | The Current Start of Paging, Used for Paging to Get Data. Example: Select \* from Users Limit {{table1.pageSize}} Offset {{table1.pageOffset}} |
| displayData | Array | Data Displayed in the Current Table |
| filter | Object | Table Filtering Parameters |
| data | Array | The JSON Data for the Table |
### Events
Events give you the ability to trigger further actions (with Event-Handlers)
| Event Name | Description |
| ----------------- | -------------------------------------- |
| Save Changes | When a user clicks "Save Changes" |
| Cancel Changes | When a user decide to skip Changes |
| Row Select Change | When the selected Row Change |
| Row Click | When a Row is Clicked |
| Row Expand | When a Row gets Expanded |
| Row Shrink | When a expanded Row shrink |
| Column Edited | When a Column gets Edited |
| Search | When a user make a global Search |
| Download | When a user Download Table Data |
| Filter Change | When a Filter Change |
| Sort Change | When a Sorting Change |
| Page Change | When a user changes the displayed Page |
| Refresh | When a user Refresh the Table View |
### Methods
You have the capability to engage with components via their respective methods, which can be accessed by their designated names within any segment where JavaScript is utilized. Additionally, these components can be activated through the 'Control Component' action, which is triggered in response to specific events
| Method Name | Description |
| --------------- | ----------------------------------------- |
| setFilter | Set the Value of Property filter |
| setPage | Set the Value of Property page |
| setSort | Set the Value of Property sort |
| resetSelections | Set the Value of Property resetselections |
\\
# Messages / Toast
The Toast component is a versatile tool for displaying brief notifications ("toasts") within an application. It supports various configurations to customize the appearance, behavior, and placement of toasts. Below is the documentation for the Toast component and its methods.
#### Syntax
```javascript
toast.open(title, options);
// toast.open( title: string, options?: { message?: string, duration?: number = 3, id?: string, placement?: "top" | "topLeft" | "topRight" | "bottom" | "bottomRight", "bottomRight" = "bottomRight", dismissible?: boolean = true } )
```
#### Parameters
* **`title`** (string): The title of the toast notification. This is a required parameter and will be displayed prominently on the toast.
* **`options`** (Object): An optional configuration object that allows you to customize the toast notification. The properties available in this object include:
* **`message`** (string): Optional. The message to be displayed on the toast. Provides additional information about the toast notification.
* **`duration`** (number): Optional. The duration for which the toast should remain on the screen, specified in seconds. The default value is `3` seconds.
* **`id`** (string): Optional. A unique identifier for the toast. This can be used for targeting specific toast notifications if needed.
* **`placement`** (string): Optional. Defines where on the screen the toast will appear. Possible values are `"top"`, `"topLeft"`, `"topRight"`, `"bottom"`, `"bottomRight"`. The default placement is `"bottomRight"`.
* **`dismissible`** (boolean): Optional. Determines whether the toast can be dismissed by the user before the duration expires. The default value is `true`, making the toast dismissible.
#### Return Value
The `toast.open` method does not return a value.
#### Examples
**Basic Usage**
To display a simple toast with just a title:
```javascript
toast.open('Hello World!');
```
**With Message and Duration**
To display a toast with a title, message, and custom duration:
```javascript
toast.success("Query runs successfully", {duration: 10});
```
**Custom Placement and Dismissibility**
To display a toast at the top of the screen, which is not dismissible:
```javascript
toast.warn('Alert!', { message: 'System will undergo maintenance tonight.', placement: 'top', dismissible: false });
```
#### Customization
The Toast component also provides additional methods for displaying toasts with predefined styles and icons corresponding to different notification types: `info`, `success`, `warn`, and `error`. These methods have the same signature and options as `toast.open`, but they display toasts with colors and icons that are appropriate for their respective notification types.
* The toast will automatically disappear after the duration has elapsed unless `dismissible` is set to `false`. In that case, the user must manually close the toast.
* If multiple toasts are triggered with the same `id`, they will be treated as separate instances unless custom logic is implemented to handle such cases.
* The placement of the toast might need to be adjusted based on the overall layout and responsiveness of the application to ensure optimal visibility on different devices.
Each of these methods accepts the same parameters as `toast.open`, allowing for customization of the message, duration, ID, placement, and dismissibility.
* **`toast.info(title, options?)`**: Displays an informational toast with a blue icon.
* **`toast.success(title, options?)`**: Displays a success toast with a green icon.
* **`toast.warn(title, options?)`**: Displays a warning toast with a yellow icon.
* **`toast.error(title, options?)`**: Displays an error toast with a red icon.
**Additional Methods**
**`toast.destroy(id?)`**
Destroys an open toast. If no ID is provided, all toasts will be closed.
* **Parameters**:
* `id` (string, optional): The unique identifier of the toast to destroy. If not specified, all toasts will be destroyed.
# Calendar
The Calendar Component is a feature-rich way to organize and edit date and calendar entries in OpenFlower. To offer the best experience for Calendars, we integrated the [fullcalendar.io](https://fullcalendar.io/docs) Project.
You can refer to the documentation like this:
### Dynamic Data for Events
In the "Basic" section, you can bind your Datasource to feed the calendar with your existing Events.
The JSON structure is an array of objects, where each object represents a single event on the calendar. Here's a breakdown of what each key in the object means:
* **`id`**: A unique identifier for the event. This is a string that helps distinguish each event from others.
* **`title`**: The name or title of the event. This is a brief description that will be displayed on the calendar to represent the event.
* **`start`**: The start date and time of the event. This should be in the format "YYYY-MM-DD HH:MM:SS". For all-day events, you can omit the time part and only provide the date.
* **`end`**: The end date and time of the event, following the same format as the start date. For all-day events that last multiple days, this indicates the end date.
* **`color`**: (Optional) A string representing the color code (in hexadecimal format) to be used for the event's display on the calendar. This allows for visual differentiation between different types of events.
* **`allDay`**: (Optional) A boolean value (`true` or `false`) indicating whether the event lasts all day. If `true`, the event will be shown as an all-day event, possibly in a different section of the calendar or styled differently. If this key is omitted, the event is treated as having specific start and end times.
```
[
{
"id": "1",
"title": "Coding",
"start": "2024-03-04 09:00:00",
"end": "2024-03-04 23:30:00",
"color": "#079968",
"allDay": true
},...
]
```
As soon as a user edits or adds a new Event, the data object is updated so that you can persist this change on your chosen Datasource.
```
// Access all current calendar event data
return calendar1.events;
```
### Editable Calendar
Based on the Setting "Editable" you can allow your Application Users to add or edit own Calendar Events. A small modal opens and allows the entry of Event information.
### Premium Views
To display the Premium Views (Resource Timeline and Resource Grid), you must purchase a License at per Developer Seat. This License is then valid for all App Users in the Role "Member / Viewer".
You can enter the License Key in the Property Settings Menu. As soon as you enter the License Key, the Premium Views will be available at the Dropdown "Default View".
# Date handling
Day.js is a lightweight JavaScript library for parsing, validating, manipulating, and formatting dates and times, designed to be a simpler and smaller alternative to Moment.js.
Day.js is already included in OpenFlower, so you can directly begin using it to work with dates and times by creating Day.js objects using `dayjs()`. This function accepts various formats, including strings, Date objects, and UNIX timestamps, allowing for flexible date and time manipulation such as adding or subtracting time, formatting dates, and comparing dates.
{% hint style="info" %}
You can read how to use Day.js in their excellent Documentation here:
{% endhint %}
### Day.js Plugins
To enhance Day.js's functionality, developers can utilize its plugin system, which allows for the inclusion of additional features not available in the core library.
Since OpenFlower Version 2.3.1, we load all DayJS plugins automatically
{% hint style="info" %}
An overview of Day.js Plugins:
{% endhint %}
You can use Day.js Plugins at all places in OpenFlower that support {{ }} Handlebar notation.
```javascript
Quarter: {{dayjs().format('Q')}}
Day of Month with ordinal: {{dayjs().format('Do')}}
Week of year: {{dayjs().format('w')}}
{{dayjs('2013-11-18 11:55').tz('Asia/Taipei')}}
```
# Bulk Editing
Settings & Properties for components can sometimes be repetitive. That means you would like, for example, to change the Background Color for some components. Till OpenFlower Version 2.3.1 you needed to set up this for each Component individually, which means a lot of Clicks.
With Version 2.3.1 we introduce the ability to edit Properties for many selected Components at once.
{% embed url="" %}
The "Apply Action" tries to set the Property Value at all selected Components. It depends then on the Component if this Property is supported. If not, the Action for the individual Component is simply ignored. For all other Components, it takes effect immediately.
# Layers
OpenFlower offers the fantastic feature of enabling a mode where components can freely overlap on the canvas, combined with precise control over the layering of these components. This advanced functionality diverges from traditional grid-based placement constraints, offering developers and designers unparalleled UI/UX creation flexibility.
The control over component layering empowers you to build interfaces that are not only highly functional but also aesthetically pleasing. Layers are an essential step towards the Vision of OpenFlower to merge the ability to create "Apps, Websites, Presentations, and Collaboration Tools" inside a single Lowcode Platform.
From Version 2.3.1 on we introduce this feature in several steps and develop it further by the feedback of the OpenFlower Community.
### Step 1 - Simple Layers
In the App Editor, we introduce a setting to switch on the "Layer Feature" within the App Editor.\
Each App that is edited during this feature is switched on will become capable of organizing components in layers. Existing Apps will look exactly the same till you start to place components differently. However, by the nature of "Layers", the positioning of components is "fixed" in a vertical & horizontal manner.
That means that you need to plan the layout differently, as the automatic "pushing down" of visual components with "auto-height" will not be effective in the Layers Mode. Each component is defined at the same time as a single layer. In other words, the app has as many layers as you place Components to the Canvas.
### Step 2 - Layer Groups & deep Layers
In Version 2.4.x we will activate Layer Groups to help you to organize components in a layer group together. A layer group will behave like a single Layer.
Deep Layers are the possibility to organize Layer Positions for Components inside of Containers & Lists. (Child Components). The Layer & Selection List shows already the full Hierarchy, but limits in Step 1 the possibility to the root-level of Components.
### Step 3 - Layers & automatic vertical scaling control
When we activate Step 3, you will be able to control the vertical auto-scaling of components in connection to the current layer group and other elements on the Canvas.
## Using Layers
In the new "Layers" Settings Menu on the left Sidebar you can open the Settings regarding Layers, Bulk edit, and Layout.
{% embed url="" %}
### Organize Layer Position
To change the Layer Position and move Components in front or back of each other, simply use the drag n drop List on the left Layers Settings section.
{% embed url="" %}
# Data selection & Javascript
When building apps in OpenFlower, you can use JavaScript (JS) to access and transform data from objects, including components, queries, and global parameters. When writing JavaScript inside SQL editor, component property's input box, table column settings, etc., always remember to enclose all your JS code inside double curly braces, such as\
`{{'hello, ' + currentUser.name}}`.
## Access data
Objects have globally unique names, such as `input1`, `query1`, and `table1`. You can refer to the properties of the objects in your app by JS code.
### Access data in an object
OpenFlower supports you accessing the data in an object using dot notation (`objectName.keyName`). For example,`{{userInfo.selectedRow.userName}}` accesses the `userName` value in the currently selected row of **Table** `userInfo`.
When writing JS in `{{ }}` to access values in an object, add a `.` after the object name to trigger an autosuggest menu in case you are not sure about objects' built-in properties or methods.
**Example**
This GIF shows how the dot notation triggers an autosuggest menu and displays the properties of `table1`.
### Access data in an array
You can access the values in an array by index. The index always starts at 0, so you can use `array[0]` to access the first element of the array.
**Example**
The **Data** property of **Table** component is an array of objects. This GIF shows how to access the value of `first_name` in the first element of the **data** array in `table1`.
## Transform data
You can leverage built-in JS functions and third-party libraries in `{{ }}` to transform data, such as `filter()`, `map()` and `reduce()` operations.
**Examples**
Lowercase a string.
```javascript
{{input1.value.toLowerCase()}}
```
Change date format.
```javascript
{{moment(table1.selectedRow.date_column).format('YYYY-MM-DD')}}
```
Return name from query results.
```javascript
{{query1.data.map(i => i.name)}}.
```
## Restrictions
The JS code in `{{ }}` should be a single-line code, such as `.map()` or `.reduce()` combined with an arrow function or a ternary operator.
**Examples**
```javascript
{{query1.data.id.length}} // ✅ to reference a value
{{query1.data.map(row => row.id)}} // ✅ .map() + arrow function
{{ num1 > num2 ? num1 : num2 }} // ✅ ternary
```
The following JS code examples are illegal in `{{ }}`.
```javascript
{{
// ❌ you can't write code like this in {{ }}
const array = query1.data;
const filterArray = array.filter(it => it.value > 10);
return filterArray;
}}
```
If you wish to orchestrate multiple lines of JavaScript, OpenFlower supports you writing such code in transformers.
```javascript
// codes inside a transformer
if (select.value === "1") {
return "Option 1";
}
if (select.value === "2") {
return "Option 2";
}
return "Option 3";
```
## View data
Data from queries can be complicated and nested in real cases. Viewing data provides you with the detailed structure of data in objects and helps you understand your data better. Before accessing or transforming data, you may need to view the data and its structure first. OpenFlower offers three ways to view data.
### View query result
After running a query inside the query editor by clicking the **Run** button\*\*.\*\* Query result is displayed in the format shown below.
### View data in Data Browser
Data browser located in the left pane displays all of the data inside your app. You can click on the node to expand and view the data structure.
### Real-time view
When setting up properties or writing JS code inside an editor, you can view the evaluated result in real-time in a box below your editor.
# Use Markdown
OpenFlower supports you using the lightweight markup language Markdown to format texts in your app, such as changing the font size, inserting code, and adding a list. You can also embed HTML-formatted text in Markdown for more styling options.
Use Markdown in **Text** and **Table** components.
* **Text**: Use Markdown for the input text.
* **Table**: Use Markdown for column type.
## Markdown basics
All Markdown syntax is valid in OpenFlower.
* **Headings**: Use hashtag (#) before heading. More hashtags, lower heading level.
* **Paragraphs**: Use a blank line to separate texts into paragraphs.
* **Line breaks**: Add at least two whitespaces at the end of a line and press **Enter** to start a new line.
* **Emphasis**: Use single asterisk (∗) before and after text to convert it to *italic* text, double asterisks (∗∗) for **bold** text, and triple asterisks (∗∗∗) for ***italic bold*** text.
* **Blockquotes**: Use the closing angle bracket (>) to create a blockquote.
* **Lists**: Use hyphen (-), asterisk (∗), or plus sign (+) followed by a whitespace to create an unordered list, and use numbers followed by a period (.) to create an ordered list.
* **Code**: Use backticks (\`) before and after code to denote `` `code` `` in plain text, and three backticks (\`\`\`) to present ` ```code block``` `.
* **Horizontal rules**: Use at least three asterisks (∗∗∗), hyphens (---), or underscores (\_ \_ \_) at the beginning of a line to create a horizontal rule.
* **Links**: Use square brackets (\[]) for the display text and parenthesis (()) for the link address. Note that no space should be inbetween. For example, `[OpenFlower](https://docs.openflower.org)`.
* **Images**: Use an exclamation mark (!) to start an image shiinsertion, and then use square bracket (\[]) for the alternative text and parenthesis (()) for the link address or source path. The caption can follow the parentheses or start at a new line.
* **Escaping characters**: Use backslash (\\) to display the special symbols that Markdown uses. For instance, to print ` `` ` in plain text, you should use `` \`\` `` in Markdown.
For more information, see [Markdown guide](https://www.markdownguide.org/basic-syntax/).
## GFM extension
You can also use GitHub Flavored Markdown (GFM) extensions for additional syntax.
* **Footnotes**: Use caret (^) and number in square brackets (\[]) to insert footnotes. For more information, see [Footnotes](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#footnotes).
* **Strikethrough lines**: Use double tilde (\~\~) before and after text to add strikethrough lines. For more information, see [Styling text](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#styling-text).
* **Tables**: Use hyphens (-) separated by the vertical bar (|) to create the header row of a table, and continue using the vertical bar to separate content in cells. For more information, see [Tables (extension)](https://github.github.com/gfm/#tables-extension-).
* **Task lists**: Use a whitespace in square brackets (\[ ]) within the list format to create task lists. To mark a task completed, replace the whitespace with the letter *x*. For more information, see [Task lists](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#task-lists).
## HTML support
In OpenFlower, you can use most HTML tags and properties. For more information, see [Embed HTML in Markdown](https://www.markdownguide.org/basic-syntax/#html).
{% hint style="warning" %}
For security reasons, a few HTML tags including **iframe** and **script** are not permitted in OpenFlower.
{% endhint %}
### Appendix: Supported HTML tags
```html
