If you have some existing data, the fastest way to get data into a Budibase table is to import it using a CSV.

Budibase will assume that your file is comma-separated and that the first row is a header row - i.e. it contains your column names.

To create a table with a CSV:

1. Click on “Budibase DB”

2. Click “Create new table”

3. Give your table a name

4. Click the “Upload” button, and choose your CSV file

5. Click “Create”

Budibase will read your file, and display the column names that will be created. By default, all columns will be of type “Text”. However, you may change the column type at this point.

CSV import does not support relationships.

Attached below is our “Vehicles.csv” file, if you’d like to use this to try out the import.

Budibase comes with its own pre-packaged database. Within Budibase, you can create tables and columns, set up relationships between tables, and manage the data contained in the tables.

This guide will show you how to create a simple CRUD application with Budibase DB. We will build a Vehicle Maintenance Log, consisting of

• A Vehicles table.

• A Service Log table, to record the service history of a vehicle

When users log into our app, we want to present them with a list of recent Service Logs - i.e. a list of Service Logs, in descending order of “Service Date”.

To achieve this we:

1. Navigate to the home screen, under “Design”.

2. Remove any default component that are on the page.

3. Add a “Data Provider” component.

4. Give the data provider a name, so that we can easily identify it in our component tree (left panel).

5. Setup the data provider to connect to the “Service Log” table.

6. Set the “Sort Column” to “Service Date”

7. Add a table component, underneath the data provider

Budibase is an open-source low-code platform for building internal applications, such as admin panels, internal tools, client portals, and more. The Budibase documentation site will explain how to set up, use, and contribute to Budibase. Welcome to the community Budi!

🚀 Quickstart tutorials

No time, no worries. Get started quickly with Budibase using the following tutorials:

🌐 Get started with self-hosting

Click the link below to find out how to self-host Budibase.

👐 Make a contribution

We are now going to list Service Logs on our home screen, ordered by the most recent logs - by Service Date.

To achieve this we:

1. Navigate to the home screen, under “Design”.

2. Remove any default components that are on the page.

3. Add a “Data Provider” component.

4. Give the data provider a name, so that we can easily identify it in our component tree (left panel).

5. Setup the data provider to connect to the “Service Log” table.

6. Set the “Sort Column” to “Service Date”

7. Add a table component, underneath the data provider

8. Finally, we select the columns that we want to see in the table

At the time of writing, Budibase has fantastic support for Postgres, MySQL and MariaDB. We intend to add more SQL connectors.

We automate all the most common SQL queries - INSERT, UPDATE, DELETE and SELECT by ID. You can also write custom queries if you need something more complex or use stored procedures.

This guide will take show you how to build a “Vehicle Maintenance Log” application. For this guide, I will use Postgres. As far as Budibase is concerned, the process is the same, regardless of your database.

We will use the following table structure.

Below are Postgres and MySQL scripts to create the necessary tables, and insert test data.

The first step is to connect to your database.

The connection options will be slightly different, depending on your database. The example below uses Postgres.

Note that if you are connecting to a database on `localhost`, your host should be set to `docker.host.internal`, or `172.17.0.1` if running on Linux.

Once you have input your connection details, click on “Fetch tables from database”. This will read all the tables in your database.

Next, we are going to add a “Create new” button to our Service Log. We want to enter the new details into a form - inside a modal.

First, we will create and configure a button.

1. Create the button, and position it on the screen using a container. We place the container above our Service Log table, place the button inside, and right-align it.

2. Click on your button, and choose “Define Actions”.

3. Add a “Navigate To” action, with the URL “/service-log/new/row”, and tick the box to “Open screen in modal”.

Next, we will create a new screen that allows us to create new “Service Log” rows.

1. Click the “+” button to create a new screen.

2. Select the template “Service Log - new”.

3. Set the URL to “/service-log/new/row”.

4. Click “Create”. This will bring you to your new screen.

5. Click on the “Save” button on your new screen, then “Define Actions”.

6. Remove the “Navigate to” action.

7. Add a new action for “Close Modal”.

Once Budibase knows about your SQL tables, it can autogenerate screens (the user interface) that allows listing, creating, editing a deleting of records from tables.

Of course, these generated screens are completely customisable - but Budibase gives you a huge headstart.

1. Go to the “Design” section.

2. In the left panel, click the “+” button, to create a new screen.

3. For the “Template”, choose “Vehicles - List”.

4. Click create

This produces a screen that lists row in the Vehicles table. You can now repeat the steps above for “Vehicles - New” and “Vehicles - Detail”, to give you “Create” and “Edit” screens. For these screens, it’s best to uncheck the “Create Link in navigation bar”.

If you do not have CSV data to import, you can build the table yourself.

To create our “Service Log” table:

1. Click on “Budibase DB”.

2. Click “Create new table”.

3. Call your table “Service Log”, and Uncheck “Generate screens in design section” - we will add these manually.

4. Create the following columns

   1. Description - Text.

   2. Vehicle. A relationship to the Vehicles table (one Vehicle has Many Service Logs)

   3. Service Date - Datetime.

   4. Category - Options. Our options will be Brakes, Tyres, Engine and Transmission, each separated by a new line.

   5. Mileage - a number.

5. Finally, create some rows in the Service Log table, so that we have data to test with.

Budibase allows you to declare relationships between your table. We are going to set up our one-to-many relationship between Vehicles and Deals.

Note that Budibase does not modify your tables. We are simply telling Budibase about your existing database structure.

To create a relationship:

1. Select your SQL datasource

2. Click on “Create Relationship”

3. Set relationship type to “One”

4. The from (“One”) table is “Vehicles”

5. The to (“Many”) table is “Service Logs”

6. The “From Table Column” is how your relationship will be named in your Vehicles table. We will call this “Service Logs”.

7. The “To Table Column” is how your relationship will be name in your Service logs table. We will call this “Vehicle”

The relationship is now created, however, we need to tell Budibase how to describe the Vehicle from the Service Log table, and vice versa. To do this, we need to set the “Display Column”. This is equivalent to a column alias:

SELECT ServiceLogs.*, Registration as Vehicle

FROM ServiceLogs

INNER JOIN Vehicle on ServiceLog.VehicleId = Vehicle.id

I.e. use the Vehicle “Registration” column when displaying it in the Service Table.

So, we will set up our display columns

1. Click “Update Display Columns”

2. For “Vehicles”, choose “Registration”

3. For “Service Log”, choose “Description”

Now, we want the ability to create a new todo item, directly from the todo list. To achieve this, we will:

1. Create a new form, inside your data provider

2. Add a text input to the form.

3. Set the input’s “Field” property to Title. We will use this to create a new item.

4. Add a button to the form.

5. Click on “Define Actions”, to set the button actions.

6. Add an “Execute Query” action, and choose your “Create new item” request.

7. Assign the item_title parameter to your text input value.

8. Add a “Clear Form” action. This will clear the input, after the request has been executed.

9. Add a “Refresh Data Provider” action, and choose your data provider. This will reload the list, to display your new item.

Now that we have created our query, we want to display these items in our app.

1. Go to the design section.

2. In the Home screen, delete the default component.

3. Add new Data provider, setting the “Data” to “List Items” - i.e. our query.

4. Add a new Repeater, inside the Data provider.

5. Add a Paragraph element, inside the repeater.

This guide will show you how to build a CRUD application, with the Budibase REST API connector. For this example, we will build a Todo list, using GitHub Issues to store our items.

If you want to follow along, you will need to:

1. Create a GitHub repository.

3. Add a few issues to your repository, so that we have some data to test with.

Next, we are going to add a “Create new” button to our Service Log. We want to enter the new details into a form, inside a modal.

First, we will create and configure a button.

1. Create the button, and position it on the screen using a container. We place the container above our Service Log table, then place the button inside, and right-align it.

2. Click on your button, and choose “Define Actions”.

3. Add a “Navigate To” action, with the URL “/servicelog/new/row”, and tick the box to “Open screen in modal”.

Next, we will build the screen for “New Service Log”.

1. Click on the “+” button to create a new screen.

2. For “Template”, choose “ServiceLog - new”.

3. Set the URL to “/servicelog/new/row”.

4. Uncheck “Create Link in navigation bar”.

5. Click “Create”.

6. Budibase has generated a form for us, but we should remove some unnecessary columns:

   • ID - this is generated by our database

   • VehicleID - this is handled by the “Vehicle” dropdown

7. Finally, we need to tell our screen to “Close Modal” on save, which is not the default action for this type of screen.

   • Click on the “Save” button

   • Click on “Define Actions”

   • Remove the “Navigate To” action.

   • Add a “Close screen modal” action.

Next, we want to add the ability to create a new item from our Budibase app. We want to be able to pass in the item title, to the create query. To do this, we’ll create a query with parameters:

1. Click on your GitHub datasource

2. Click “Add Query”

3. Enter the name “Create new item”

4. The function is “POST”

5. Add a parameter called “item_title”

6. Set the “Path” to /repos/<github_user>/<github-repo>/issues

7. Set the Body to { “title” : “{{ item_title }}” }. This will pass our item_title parameter into the “title” field, in the JSON body.

8. Test your query to make sure that an issue is created.

We will use GitHub issues to represent our todo items. So, we need to create a query that will list GitHub issues.

1. On your API connector, click “Add Query”

2. Call your query “List Items”

3. The “Function” should be GET

4. For the “Path”, enter /repos/<your_github_username>/<your_repo>/issues.

5. Click on “Run Query”. This query should run successfully. The schema should be that of a GitHub issue.

6. Click “Save Query”

First, we must add a new REST API connection and set up some basic configuration.

1. Click the “+” button, in the Data section.

2. Give your datasource a name - this is how it will appear in Budibase. I called mine “GitHub”.

3. Set the URL to https://api.github.com. All requests made through this connector will be prepended with this URL.

4. Add a new “Default Header” for “Authorization”, with the value “token your-token” (replace “your-token” with your GitHub personal access token. All requests made through this connection will include this header.

5. Click Save

For every item in our list, we want to display a “Done” button. When clicking on the button, the GitHub issue should be closed and our item should disappear from the list.

1. Create a new query on your GitHub datasource

2. Name your query “Mark as Done”

3. Select the PATCH function

4. Add a new parameter called “item_number”

5. Set the path to /repos/<github-username>/<github-repo>/issues/{{ item_number }}

6. Set the body to { “state”: “closed” }

7. Save your query

Now, we can use this query in our user interface.

1. First, we will add a new container inside our repeater. We want to display the button and title alongside each other, so must use a container to achieve this layout.

2. Drag your title “Paragraph” component inside the container.

3. Add a button to the container and set the text to “Done”

4. Now, click on “Define Actions” for the button

5. Add an “Execute Query” action, choose the “Mark as done” query, and pass in the GitHub issue number as a parameter.

6. Add a “Refresh Data Provider” action.

Our app is a simple Todo list, and we would like to display the list in the center of the page, without a navigation bar.

1. Add a new container to the Home screen.

2. In the component tree, drag your data provider inside the container.

3. Set the container’s Align Items property to “Center”

4. Click on your Home screen in the component tree, and change the “Layout” to “Empty Layout”. This will remove the nav bar.

5. Finally - set your theme to “Darkest”!

Below you can see a list of available datasources. The way you connect to and use them differs a bit so in the next we sections we will explore them in more detail.

The data section is where you add and manage your data. Budibase apps rely on data and it is strongly advised to create your data structure before designing your web application. Your data structure will involve tables, columns, rows, and views - these are the building blocks that hold and present your data in a structured manner.

Getting started

When adding a data source in Budibase you can either create Budibase "native" sources or connect to external ones.

To add a source, simply hit the "+" button in the top left next to the "Sources" headline.

You will be presented with a modal that shows you all the different source types you can use. In the next few pages we will take a closer look at a few of these.

You are free to mix and match sources as you like. Create an internal table, pull in some data from a Postgres database and/or connect to a REST API.

Creating or editing user roles

The Users Table in the data section is where you manage access, create and edit roles. These are then applied in the User Management page.

Adding user meta data

You can also add columns that are specific to your application here. This data will only be available in this app.

This datasource is the one that is native to Budibase. Any data you add here is stored directly on your Budibase instance.

Creating a table

Creating the table itself is pretty straight forward. Go ahead and enter a name.

Next up you have a number of "Auto Columns" you can pick and choose from. These columns will tell Budibase to add some extra information when new records are added or updated.

For example, selecting Created by and Updated by will add data to your records who created or updated the record is. Selecting Created at and Updated at will show you when a record was created and updated. The Auto ID option will add an auto incrementing ID column to your records so you can keep track of them more easily.

There's also a Generate screens in Design section option. Selecting this will auto generate screens in the front-end. We will talk more about this when we get to the Design section.

Importing Data

If you already have some data in the form of a CSV you can upload one here. Let's take a look at that. If you want to play around with a sample you can go ahead and use the one that has been added below.

When you have uploaded your CSV you will be presented with a number of new options. One for each column. It will look something like this:

Before you create your table you need to select what types each column should have. At the moment you can select between Text, Number, Date, Option and Boolean. It's very important that you select the correct thing here as the type is what determines much of what you can do with it later on in the Design section.

As only you know what your data looks like you will have to pick what makes sense here. Text is generally used for things like descriptions, long-form content, IDs containing letters among other things.

Number is a type that you should use when working with numbers; sales numbers, number of items in some inventory, revenue, profit, etc.

Date is for things like date of sale, shipping dates and so on.

Options can be used when you want a user to be able to pick between a number of different options. For example. In the Sales CSV that we imported above there's a Sales channelcolumn. It has two options: online and offline. When a user wants to add a new sale, this will allow them to pick between these two options rathern than type it in manually - much less error prone.

Picking something that does not make sense will result in a warning next to the column.

Adding or Editing Columns

Once you have imported or created a table you see it added to sidebar on the left under Sources. If you want to add or edit new column types you can do so by clicking the Create column button or by hovering on one of the already existing columns and clicking on the small edit button that appears.

Datatypes

Adding data

Adding data is simple. click the Create rowbutton and you will be presented with a modal. Fill in all the data and hit save. If you set up your column types correctly when you created or imported your table you will now see the correct controls here. A date picker, option picker, etc.

Most companies already have big databases that they want to pull data out of and use in their internal applications. Let's take a look at how we can connect to one.

Connecting to the database server

We will start by creating a new datasource. Click the + button next to the sources heading in the sidebar on the left. Enter a name for your connection and select the SQL source of your choice. In the example below we'll be using Postgres.

Once created you will be presented with a new screen. where you will have to enter your connection information. Enter the relevant information; host, port, database name as well auth information. Once you're done. Hit Save. If successful you will get a notification confirming that your datasource has been updated.

Fetching tables

To fetch the tables from your database click the Fetch tables from databasebutton. You will be presented with list of all the tables. Before veturing forth, update the display columns so that they make sense by clicking the button.

Creating relationships

To help Budibase understand your database you will need to create the relationships. In our example we have products that are related to our tasks via many-to-many relationship. Let's take a look at how something like that would look:

Through/join tables are only for many-to-many relationships in SQL.

If you have a direct mapping of 1:N with a foreign key you do not need a through table if you have a foreign key. To set up a relationship select One and link to the other table. Select the foreign key.

Writing your own Query

There are situations where you need more than a simple CRUD interface. In order to around that we also have the ability to write our own SQL queries. To get started, hit the Add query button. On the next page you will have to enter a name for the query as well as select the function you want to perform and last but certainly not least, enter your actual actual SQL.

After writing your query, hit the run query button. If successful you will be presented with a JSON schema. Click the Schema button and select the appropriate data types for the different fields. When you are satisfied with the query, hit Save Query.

The REST datasource is a powerful integration in Budibase that allows you to connect to data over HTTP.

Creating a new REST datasource

To create a new REST datasource use

• Data>Sources>Add>Rest>Continue

Configuration

Add additional configuration to your datasource in the form of queries, default headers, authentication and variables. Use the Save button when you have completed your changes.

Name

By default the REST datasource will have a name like REST or REST-1, you can change this to something recognisable if desired.

Queries

A query is an individual request in the rest datasource. Either create one from scratch or import an existing. For more details see:

Headers

Default headers that will be added to every query in the datasource.

Authentication

Configure authentication strategies that can be added to queries in the datasource. For more details see:

Variables

Create static or dynamic variables that can be used in queries in the datasource. For more details see:

Additional Operations

Use the navigator to perform additional operations on queries

• Delete

  • Delete the query

• Duplicate

  • Create a copy of the query

Use bindings to supply additional information to a query at runtime. In this example we have

• An API endpoint that accepts a status field to filter a list of applications

• A query named applications

• An application that supplies data to the bindings of the query

Creating a binding

We can create a binding named status with a default value of all.

Using a binding

Using handlebars the binding can be referenced throughout the query in the following places:

• URL

• Params

• Headers

• Body

• Transformer

Params example

The binding can be used as the value of a param of the same name. While the name can be shared it is not required.

Headers example

The binding can be used as the value of a header of the same name. As above the binding and header name may or may not be shared.

Body example

The binding can be used in any part of the request body. e.g. as the value of a json field.

Supplying data to a binding

In our application we have the following structure:

Form: Status Form

The form that will hold the value of our selected status. This is the top level component so that the value can be accessed by components nested underneath.

• Type: Create

  • While this form does not create anything, this option is required to indicate that the input schema (the bindings) should be used rather than the schema returned by the query.

  • Update may also be used to the same effect.

• Schema: applications

  • The input schema of our REST query

Options Picker: Picker

We use an options picker in the form to provide our possible status values.

• Field: status

• Adds the selection to the form under the name status

• Options source: Custom

  • Custom options are specified using the Define Options drawer

Data Provider: Applications provider

We use a data provider to run the REST query

• Data: applications

  • The REST query

To link the query bindings to the form we use the bindings drawer

The value of the binding is {{ Status form.Fields.status }} which represents the status field in our form.

Conclusion

We are now able to:

• Specify a binding used in a REST query

• Specify where the value of that binding will be used using handlebars

• Create an application that supplies data to the binding and runs the query

Under construction.

The REST query import feature allows you to import one or more queries at a time.

Import Formats

The supported formats for import are:

• Swagger 2.0 / OpenAPI 2.0 (yaml or json)

• CURL

Import Sources

URL

Enter the link to your API documentation.

File

Upload a file containing your API documentation.

Text

Enter the documentation string directly.

When the import completes the new queries will be displayed in the datasource

Import into a new datasource

To import queries into a new datasource use

• Data>Sources>Add>Rest>Import

Import into an existing datasource

To import queries into a new datasource use

• Data>Sources>Select REST source>Queries>Import

Creating a new request

First, create a REST datasource if you do not have one already. For more details, see:

Use the Add query button to open the query editor.

Name

Give your query a recognizable name that will appear in the datasource navigator. For example, a query that retrieves a list of applications could be called applications.

URL

Enter the URL of the API endpoint you are using. The URL is the requested resource including the protocol, domain name, and path.

Method

Select the HTTP method used by the API endpoint you are using.

• GET retrieves data from an API.

• POST sends new data to an API.

• PATCH and PUT update existing data.

• DELETE removes existing data.

Access level

Select the access level required by the logged-in end-user. If the user visits a page where a query is executed and the access level is beyond the scope of the user's access the query will not run.

Params

URL parameters can be configured in the params tab.

• Parameters are appended to the end of the request URL, following ? and listed in key value pairs, separated by & using the following syntax: ?status=all&other=value

Bindings

For more information on using REST bindings see:

Headers

Use headers to supply key-value pairs accepted by your API.

• Switch the Active toggle to off to prevent the headers from being sent while keeping it's configuration.

Body

Use a request body to send information to an API endpoint.

• The Content-Type header will automatically be set when using:

  • raw(JSON) / application/json

  • raw(XML) / application/xml

  • raw(Text) / text/plain

• If you manually select a Content-Type header, that value will be overridden by the body type

Transformer

Transformers can be used to augment the format of the returned data.

For more information on using query transformers see:

Authentication

Preset authentication strategies configured at the REST datasource level can be used to authenticate queries.

For more information on using REST authentication see:

Sending the request

When your query is crafted you can use the Send button to preview the results of your query. When your query has been successfully executed you may save the query using Save Query

Using response data

When a query has run successfully the response data can be actioned on to better fit the usage in your application.

Modifying the schema

The response schema may be updated by:

• Adding or removing fields

• Changing the data type used when displaying the result in tables

Creating dynamic variables

The response schema and headers can be used to create dynamic variables

For more information on static and dynamic variables see:

Authentication configs are specified at the datasource level and can be selected from queries within the datasource. Adding authentication to a datasource allows queries to run well known authentication strategies and can reduce the amount of configuration needed when multiple queries share the same authentication.

Datasource Configuration

A REST datasource can contain multiple authentication configs of well known types.

• Multiple configs of the same type can exist

• Configs must have a unique name

The appropriate information is added to the request when authentication is selected.

• Basic Auth

  • Adds the Base64 encoded username and password to the Authorization header

• Bearer Token

  • Adds the token to the Authorization headed as Bearer token

Query Configuration

From within a query use the Auth dropdown to select the desired authentication config to be added to the query.

Variables are a useful way to reuse data across REST queries. Variables come in two forms; static and dynamic.

Static Variables

Static variables store data that does not change. These can range from constants used in the metadata of the request to information about the request itself that can be used in the URL such as API version or hostname.

Variables nested inside other variables will not be evaluated.

Dynamic Variables

Dynamic variables provide a way to chain data between queries.

• Response data from one query can be used to create a dynamic variable

  • Header

  • Body field

• The result of the variable will be cached for a short period of time

• A variable will be re-evaluated if a query using it fails, in which case the query will retry once

• A query will fail if a variable cannot be evaluated

Header Variables

Use the ... menu alongside response headers to select Create dynamic variable

Give the variable a name.

• The name must be unique

• The name will be used to bind this variable in your query. e.g cookie can be used as {{cookie}}

The variable will appear in the Dynamic Variables tab

Body Variables

Use the ... menu alongside schema items to select Create dynamic variable

Give the variable a name as above

The variable will appear in the Dynamic Variables tab

Editing Dynamic Variables

In the above example we can see the user_id variable is bound to {{ data.0.[user] }} which is an object. To access nested data in the response body we can update the variable expression to reference the nested fields using dot notation e.g. {{ data.0.[user._id] }} .

Alternatively a query transformer can be used to update the schema so that the desired field is exposed in the schema directly.

Dynamic variables can also be created manually using the Add variable button.

• Access header data using {{ info.headers.[header-name] }}

• Access body data using {{ data.0.[body-field] }}

Using Variables

Once a variable has been defined it can be used in the exact same was as a binding.

• For example a variable named my-id can be referenced in the headers, params or body of a query using {{my-id}}

When creating a column in Budibase a data type must be specified for the column. This section will cover the different data types, the use cases for them and how they're configured.

Below is a list of currently available data types for your web apps:

1. Text - the most basic data type, this is as you would expect, text in any format. The length of the text can be validated with the "max length" option.

2. Options - Similar to a text but in this case a set of options can be specified, when a user is creating/updating a row field will appear as the options that have been specified in the form of a dropdown.

3. Number - another very basic data type, this can hold a decimal number and the range can be specified with the "min" and "max" value options.

4. True/False - for use when a "yes/no" like option is required, when a user is creating/updating a row this filed will appear as a checkbox.

6. Attachment - used for storing files, like images or documents, an attachment field can store many different files at the same time, a single row can contain as many files as are related to it. When creating/updating a field of this type a file drop zone will be used.

7. Relationship - One of the more complex concepts, this allows making a link between different rows in two different tables. Row to row relationships can be compared to something like a join statement in SQL, in that they are ideal for creating many-to-many relationships. When creating/updating a row this field will appear as a multi-selection that allows selecting any number of rows.

The number data type stores numbers. A number column is a good choice if you want to store data like age, values, scores, IDs. The number column type is important when you need to do calculations within your data. Within the Number data type, you can provide min and max values. This allows you to add additional validation to your data type.

Creating a number column

The process for creating a number column takes a few seconds.

1. First, click the Create New Column button

2. Give your column a name - we used Score in the video above.

3. Choose Number as your data type

4. Give it a min of 1, and a max of 5

5. Click Save Column

6. Add data to your new column by adding rows

Using the number data type

Important considerations

• A number column can only include numbers.

• It cannot include punctuation marks, letters.

• Telephone numbers need to be stored as a text/string data type because they often begin with a 0 and if they were stored as an integer then the leading zero would be discounted.

The text data type stores text, including numbers - also known as a string. A text column is a good choice if you want to store data like names, addresses, or simple custom data. It is a popular data type and one you are more than likely going to use.

Creating a text column

The process for creating a text column takes a few seconds.

1. First, click the Create New Column button

2. Give your text column a name - we used Name in the video above.

3. Due to the popularity of the text data type, it is shown by default; so there's no need to change it.

4. Click Save Column

Using the text data type

The date/time data type stores dates. This is important when using components, or displaying information that relies on time/dates. A calendar component, for example, will utilize the date field. With Budibase, you can also provide an earliest and latest date, within your date/time data type. This allows you to add additional validation so dates added have to fall after, before, or in between the earlier and latest dates. The date's within Budibase comply with ISO8601 formating - 2020-09-24T13:12:04.622Z. Thankfully, we have a date picker that removes the need for data entry and makes life easier.

Creating a date/time column

The process for creating a date column takes a few seconds.

1. First, click the Create New Column button

2. Give your column a name - we used Date Started in the video above.

3. Choose date/time as your data type

4. Add an earliest or latest date - we added an earliest date

5. Click Save Column

6. Add data to your new column by adding rows

Using the date/time data type

The options data type stores options in the form of strings/text that are available for selection. When adding options, you must take a new line for each option.

Creating an option column

The process for creating an option column takes a few seconds.

1. First, click the Create New Column button

2. Give your column a name - we used Department in the video above.

3. Choose options as your data type

4. Add your options - we added IT, Sales, HR in the video above

5. Click Save Column

Using the date/time data type

Budibase's Group feature allows you to group your rows together based on the column of your choosing.

How to create a new Calculation

To create a new Group:

• Click the Group button

• Select the Column you would like to Group by.

• Click save

True/False is a data type that has one of two possible values (usually denoted as true/false, yes/no, Boolean). Within your UI, this is usually displayed in the form of a checkbox.

Creating a true/false column

The process for creating a true/false column takes a few seconds.

1. First, click the Create New Column button

2. Give your column a name - we used Completed in the video above.

3. Choose True/False as your data type

4. Click Save Column

5. Add data to your new column by adding rows

Using the true/false data type

Just like with the other data types, start by creating a new column. Select Formula and you will be presented with a textbox. Use Handlebars to construct the expression you are interested in and hit the Save Column button.

If you want some assistance when writing your expression you can click the lightning bolt icon to the right of the formula field. This will open a modal where you can select the fields and handlebars expressions you want directly.

Almost every web application needs to manage static files in some way.

These could be images, text files, audio files and more. With budibase, you can upload your static files to your budibase applications with ease. We are going to cover how to upload and display your files both inside the budibase builder and in your web applications themselves.

Let's get started.

The Attachment Field Type

Uploading Attachments

When you create a new row in your table by clicking the "Create New Row" button above the backend data table, you will be presented with a dropzone component for your attachment field that you can use to upload files.

Once you have selected your files, image files are processed in the background and resized. Other files are just stored as is, without any kind of resizing or transformation applied. These files will remain on your machine until you deploy - at which point they will be uploaded to the budibase hosting cloud.

Your attachments will be displayed like any regular field - inside grids and tables, forms and more budibase components.

To see attachments in action, take a look at the following example section. We will build a small app for storing country data using budibase attachments.

This section covers one of the more complex topics of your Budibase web app, the ability to create relationships between different rows. It is important to note that when a relation between two rows is formed these two particular rows become joined, rather than any particular fields in the rows being joined. The relationship is bi-directional, in that when it is created each row will have a relation to the other one. A row is also allowed to relate to many rows, meaning that many to many relationships can be created in your web app (if required).

Creating a relationship column

1. First, create/pick two tables that the relationship should be formed between.

2. Make sure that in both tables there is a column defined which can be used for display purposes, when creating this column make sure to set it with the Display column toggle.

3. Click the Create new column button in either of the two tables and select the Relationship data type from the dropdown.

Using relationships

Coming up

In this example, we will be creating a simple web application that will be used to store information about different countries around the world. Some of the information we are going to include in our application:

• Country Name

• Country Population

• Country Flag

• Travel Guide

Creating Countries Table and Columns

Next, we need to create columns in our Countries table. Let's look at the information we need to include about each country and decide which data types are the best to use for our columns.

• Country Name: Country names are just letters, so a Text type is a good fit here.

• Country Population: We should use a Number type for this.

• Country Flag: This will require an image file - here is where Attachment types come in.

• Travel Guide: We can store PDF travel guides for each country here. Let's use another Attachment type.

Watch the video below to find out how to set up your table as detailed above.

Creating Rows and Uploading Data

Now that we have set up our columns, we can start to add some rows to our Countries table. You will now notice that on row creation, you will be presented with dropzone components inside the row creation popover for both of our attachment types - Flag and Travel Guides.

Let's create an row for Spain. Follow along with the video below to find out how.

Here are the files used in the video below if you don't have your own:

Muy bien! 🇪🇸

Let's see what's been automatically created for us in the frontend of our app.

Frontend

• Countries - New: A screen with a form that can be used to create a brand new country.

• Countries - List: A screen with a table containing all the countries in your countries table.

• Countries - Detail: A screen used to represent a single country. When you click the View button in the Countries List table, you will be navigated to the detail page for that country.

Let's preview our application and interact with our attachments! Click the preview button on the top right of the builder. You will be navigated to your app in your default browser. Log in with the credentials that you set up when you initially created your app and you will see the homepage of your new app. Navigate to the automatically created "Countries" link in your navbar - you should see your countries listed in a table:

Let's dive into some of the different ways we can interact with attachments in our application.

Edit Country Attachments

Let's edit our Spain row to add another travel guide. This involves navigating to the detail view for Spain and adding another PDF file.

Delete Country Attachments

You can delete an attachment from the Country table or the Country Detail Screen. Let's delete one of our travel guides from the table view, and the other one from the detail view.

In this example, we will be creating a web app for tracking students, teachers, parking spots for teachers and classes in a school - specifically how they relate to each other.

Specifically, we are going to break these down into the three relationship types that can be modeled with Budibase. Below we will map out the relationships that we are going to create, first describing them then walking through how to build them.

One to one

The first relationship type we can model in Budibase is the most basic of types, linking two rows to each other. In this case, a Teacher is assigned a single parking spot and that parking spot can only be used by a single teacher.

One to many

The second relationship we can model in Budibase is one of the most common, linking a single row to many other rows. Here we can see that a class can only be taught by a single teacher however a teacher is capable of teaching many different classes.

Many to many

The last relationship we can model is arguably one of the most complexes but again very common in real-life systems. Here we can see that students are able to take many classes and each class can have many different students in it.

Building it in Budibase

To create this in Budibase all we need to do is:

Video demonstration

Based on the example above here is a video showing how easy it is to create in the Budibase Builder!

Within Budibase, calculations are predefinned formulas. Instead of writing the formulaes, you can simply select from the list of predefined options.

How to create a new Calculation

To create a new Calculation:

• Click the Calculate button

• Add your data

• Click save

Formulas

Sum

Avg

The JSON data type is available for internal tables. JSON fields have a schema, which can be configured when creating or editing the column. Having the correct schema is important as the builder and client library use this to know what bindings are available and what form fields are available. Extra data that is not in the schema can be stored, but no bindings will exist for it.

The JSON field schema can be edited by either a form, or by providing an example JSON payload. If you are using deep JSON structures (e.g. multiple levels of objects or arrays) then you will need to use the JSON schema editor, as the form editor only goes one level deep.

Schema editor button when creating or editing a JSON column:

Form JSON schema editor:

JSON example schema editor:

JSON field schema is merged with table schema in client apps, and basically treated as new top level columns. This means you can filter on nested values, or display them inside tables, as if they were normal fields in your table. Here's an example of a table showing all columns inside the table containing the JSON field above:

In that screenshot, you can see that it has pulled out fields from within the JSON field and displayed them automatically. It also is showing the JSON fields as a whole (as it shows all columns by default) - but you can easily control what gets displayed by using the table setting:

You can filter using fields inside your JSON. Here's an example of filtering using the nested value Car.Make:

Data bindings

Data bindings will be automatically generated for all available fields inside your JSON, including nested fields (e.g. Car.Make). Data bindings will be generated until an array is hit, at which point no further bindings can be generated. You can read about how arrays are handled down below. Bindings are also provided for the JSON field as a whole and any array fields, both of which integrate very nicely with JS bindings.

Here's an example of all the data bindings provided for the JSON field above. My table is called People and my JSON column is called Data.

Arrays

Arrays inside JSON fields can be used as data sources. For this example, I've added a new property called Friends inside my JSON field, which is an array. Here's an example using a table block to display data of `Friends. The structure is a repeater block (to get the rows that contain the JSON fields) then a table block (to show the data inside the array inside the JSON field).

You can see from this screenshot that the schema correctly determines all available fields inside the array objects and is listing them in the table. If you have an array of primitives (e.g. an array of numbers, or strings) then a fake schema entry value is generated. You can then display data inside primitive arrays using Field.something.value.

You can nest arrays as deep as you like. If your JSON structure looked something like:

{
  "array1": [{
    "array2": [{
      "array3": ["a", "b", "c"]
    }]
  }]
}

Then you can use a repeater on Column.array1, then put a repeater block inside that and target array1.array2, then put another repeater block inside that and target array2.array3, and finally get out the values. You can chain this as long as you like and the schema will always be available.

JSON form field

There is a new form field component for JSON fields. It will render a text area that pretty prints the content as JSON. It also has forced validation to ensure that the input is valid JSON.

The new JSON field component:

Validation enforcing JSON syntax:

JSON form integration

Since nested JSON fields are considered normal fields, you can bind a form component to a nested JSON field. In my example, I have the field Car.Make. If I want to update this, I can simply add a text field and bind it to Car.Make, then save my whole row as normal. This will transparently update the value inside the JSON field with no extra configuration.

Binding a form component to a nested JSON field:

When generating form components automatically (via the "Update form fields" button on field groups) the builder will always insert an actual JSON field form component for the whole JSON field, rather than individual inputs for every nested property. You can always add/remove fields as you see fit if you want to be able to directly update some nested fields.

If you have a form targetting a subsection of your JSON field, then the best way to save your full row value is to write a small JS binding and make use of the new Form.Value binding (which is an object of the whole value of the form) to insert the value into your JSON field. This is only really needed when you are iterating over JSON arrays and want to update one of the array elements.

Views are virtual tables. I understand this may seem confusing, but it is the best description, and hopefully you'll understand why after reading the following docs.

When you create a View within Budibase, it presents you with all the data from its linked Table. This provides you with canvas to manipulate your data without changing the data within the original table. This is crucial, as it protects your original data. It also allows you to create:

When designing your UI, you can reference data from your Views. So, if you have a table of sales people and their total sales, you can create a View and a Calculation which gives you the total sales of all sales people. You can then reference the data from this View in the design section of Budibase, and display the answer to the calculation.

How to create a new view

To create a new table, click the create new view button, and give it a name.

By default, a view will display all the data in your table. You should add a filter and/or a calculation to change data is displayed.

Try adding filters when:

• You need to focus on rows that meet certain conditions (e.g. Classes between May and June, and taught by Albert Einstein).

• You need to display certain information, to certain people (e.g Each sales person can only view their own commission).

How to create a new Filter

To create a new Filter:

• Click the Filter button

• Click Add Filter

• Select the Column you would like to filter

• Select a filter function

• Type your query

• Click Save

Filter Functions

1. Equals

2. Less than

3. Less than or equal to

4. More than

5. More than or equal to

6. Contains

In this section we will cover how to use Budibase data transformers, which can be used as part of data source queries. It is often a requirement when retrieving data from various sources to transform to fit your apps use case - from simply extracting properties from deeper JSON objects to enriching your data with more information transformers can be used for a wide variety of applications.

When you first create a query you'll see the transformer code editor in its own section, as seen below.

This in its basic form will return the data exactly the way it is retrieved from the data source, it is recommended to get your query up and running correctly first before altering your transformer, this will allow you to look at the initial schema of the data returned. In our example so far we have:

2. Created a query and set the path to "breweries"

3. Ran the query to see the schema

The schema for this query appears as below:

Using this information we can now write the transformer function that will be used. Initially we just want to write a function which will:

1. Work through the array of breweries that is returned by the API, in the format shown above

2. Extract the state and add it to a total count of states that have been seen

3. Return a new structure which contains only the state name and the count of breweries within

You can see the basic transformer we have written to do this below.

Here we have taken the data, written a for loop that iterates through a fills up an object with counts for each state (using the state's name as the key into the object) and finally we've mapped these totals to our output structure, an object with a state and count property. You can see from this that we can drastically change the format of the data; using JavaScript you can change the data in a multitude of ways.

This may look a little complicated, but all we have done is added a map of the state names to state codes, then at the end when we produce the final data we lookup the state name in the map and build a URL which has the code in it. You can see in our results section we now have a "flag" property, which can be used in the design section with something like an image or card component. We've thrown together a quick example of how this can all come together in your design, using only a data provider, repeater and card component bound to the "state", "count" and "flag" properties our transformer produced.

Hopefully this has helped to demonstrate how transformers can be used to get the data you need for your application, happy coding!

Components are the building blocks of Budibase. They are used to construct your user interface. At budibase we use the Spectrum design system created by Adobe. This gives you a great out-of-the-box experience where things just work. As a plus you also get themes by default.

There are a number of components in Budibase. They can be found along the top of the preview window in the Design section.

Using components

When you have added a component you will be able to see the options that you can tweak on the right side under the Settings bar. Some components also have a toolbar that will appear above it in the preview window.

Available components

Here's a list of links to the current components that are available:

Budibase uses layouts that wrap your screens. This is where you put components that you want to display across different screens. Basically a shortcut for you, so you don't have to re-build the same thing over and over.

All Budibase applications start off with two Layouts: Navigation and Empty. On the right-hand side you can see all the options that are available to you. The difference between the two starting layouts is that the navigation is turned off in the Emptylayout. Other options you will find here is the Links, where you can configure the navigation links, text options and some other goodies.

A screen in Budibase corresponds to a single page. They are either auto-generated (when you create an internal table/csv import) or you can create them manually. To do so hit the + button in the corner, next to the Screens title.

You can pick from a ready-made template that corresponds to your internal data tables or create from scratch. Enter the relevant details as well as pick what access level you want for the screen. Hit the Create Screen button. You will now have a blank canvas that you can add components to.

Budibase's Design section is often described as the frontend builder within Budibase. This is where you create and build your user interface.

Overview of the Design Section

The Design can be daunting when you see it for the first time, but in reality there isn't that much too it. Let's take a look at an example and go through the different parts of it.

On the left side you have your list of screens and components. You can also switch back and forth between Screens and Layouts. Layouts are components that wrap your screens. In the example above, if we take a look at the center of the screen, the layout in this case would be the logo, title and navigation. In subsequent pages we'll dive deeper into how to change and update the layouts.

In the middle we have the app preview window as well as the component picker (the top row with buttons). This shows you the current state of your application. Add new components by clicking on them at the top. You can also modify some of the settings from here using the toolbar.

The right side has all the settings for your component. They differ from component to component but generally this is where you will configure things such as data, margin and padding, states of varous kinds as well as conditionts and actions.

The Section component can only be used as a top-level component. It's main use is to split up your content into multiple columns. This is a great component to use when building something like a dashboard.

The section takes an unlimited number of children; the first one will be placed in the first column and the second in the second column and so on. If you add more children than there are sections it will wrap-around and start from the first column again.

You can change number of columns by changing the Type setting. There are currently four different layouts: Main with Sidebar, Sidebar with Main, Two Columns and Three columns.

The repeater component is used to loop over your data. Every child of your repeater will thus be repeated for every row in the data provider that you have selected.

A Container is a Div with pre-defined styles. They are the building blocks of your application and critical for responsive design. Containers are used to structure your application and to contain other elements in a structured way. An analogy that may help your understanding is to think of Containers as picture frames hanging on a gallery wall (your application).

The data provider component is one of the most important components in Budibase. It exposes data to your children. Whenever you want to use data from your backend or from external sources you need this component.

In addition to controlling which data source that should be available to your children it also lets you sort and filter your data. For example, let's say that we have a list of invoices in a table. To only show relevant data to the user we simply filter it on the status isPaid.

Once you have added your data provider you need to select which Data source you want to use. It's as simple as clicking the Data setting button.

Structure

Something that is worth thinking about when working with the Data Provider component is that the component structure is important. Only the children of your provider will have access to the data.

There are a number of different ways in which you can use the Data Provider; Charts, Tables and/or Repeaters.

Use the Chart component to display data from your tables to your users in a visually pleasing manner. The chart components pull in two types of values from your Tables; an X value and a Y value. The data within the column linked to the Y-axis must be a 'Number' (data type).

How to add a new Chart

To add a new chart to your designs:

• Click the chart button

• Select the chart type you would like to add

How to style your Chart

There are 4 types of charts within Budibase and they all have different settings and data requirements:

Donut Chart

The Donut Chart (also known as Doughnut chart) is a variation on a Pie chart except it has a round hole in the center which makes it look like a donut, hence the name.

The Donut Chart component comes with the following settings:

Bar Chart

The classic Bar Chart uses either horizontal or vertical bars (column chart) to show discrete, numerical comparisons across categories. One axis of the chart shows the specific categories being compared and the other axis represents a value scale.

The Bar Chart component comes with the following settings:

Line Chart

A line chart (also known as a line plot or line graph) is a chart that uses lines to connect individual data points that display quantitative values over a specified time interval. The Line Chart component comes with the following settings:

Grouped Bar Chart

Use the Table component to display data from your tables to users. With the Table component, your users can create, read, update, and delete data within the Table component, which will automatically update the data in your Tables.

How to add a new Table

To add a new form to your designs:

• Click the table button

• Within the settings panel, connect your Table component to a table in your data section.

Use the Card component to display data from your tables to your users in a structured, repetitive manner. Cards contain content and in some cases images and actions about a single subject. There is currently two types of Card component; vertical and horizontal.

How to add a new Card

To add a new Card to your designs:

• Click the card button

• Select the card type you would like to add

How to display data from your tables as Cards

• Click the Card component dropdown, and select a Card type

How to style your Card

There are 2 types of Cards within Budibase. Each Card has its own unique settings. The Card component can also accept some style updates from the Design panel i.e Background - Gradient: Heavy Rain:

Vertical

The Vertical Card is structured in a vertical manner - items are stacked on top of each other.

The Vertical Card component comes with the following settings:

Horizontal

The Horizontal Card is structured in a horizontal manner - items are stacked alongside each other.

The Horizontal Card component comes with the following settings:

Use the Text component to display Text. The Text component is versatile and can be styled using the Design panel. The Text component comes in two types: Heading and Paragraph. They both share the same settings. Both Text components can be bound to data in your Tables when used with the Repeater component.

How to add Text

To add Text to your designs:

• Click the text button

• Select the Text type you would like to add

How to add Text from your Tables

To add Text from your tables to your designs:

• In the Repeater's Setup panel, select the Table you would like to pull your data from

• Add a text component

• Select the Text type you would like to add

• Navigate to the Setup panel (on the right) and find the 'Text' textbox

• Click the ✎ button beside the textbox.

• On the left-hand side of the Binding popup, you will find a list of your columns from the table you previously selected. Click the column you would like to pull data from.

How to style Text

Within the Design panel, you will find the Typography section. You can style your text using the available properties.

How to add a Link:

To add a Link to your designs:

• Click the Link button

• Add text to your link

• Either select an option from the URL dropdown or add a URL

How to style your Link

The Link button accepts the majority of properties within the Design panel. A common style update to the Link component is to remove the underline. To do this, click Design , then open the Typography settings, reset the Decoration to None . This may already be on None. If it is, reselect None and it should work.

How to add an Icon:

To add an Icon to your designs:

• Click the Icon button

• Within the Setup panel, click the Icon button and select and Icon from the list.

How to style your Icon

The Icon component can accept multiple styling updates from the design panel, including size, color, and margin.

Use the button component to encourage users to take actions, and make choices, with a single click or tap. The Button component requires text and an action.

How to add a Button:

To add a Button to your designs:

• Click the Button button

How to style your Button

The Button component is versatile and can accept updates from all of the design properties. Once you have finished the initial design, you should enhance your button with a Hover and Active class →.

Adding actions to your Button

The image component is used to display images.

How to add a single Image:

To add an Image to your designs:

• Click the Image button

• Enter your image URL into the SRC input

How to add multiple Images from your Tables:

To add multiple Images from your Tables to your designs:

• In the Repeater's Setup panel, select the Table you would like to pull your data from

• Add an Image component

• Navigate to the Setup panel (on the right) and find the 'Src' textbox

• Click the ✎ button beside the textbox.

• On the left-hand side of the Binding popup, you will find a list of your columns from the table you previously selected. Click the Column you would like to pull data from.

How to style your Image

The Embed component is used to embed content into your web application. This content is provided by an external application or other sources of interactive content such as a browser plug-in. Types of content can range from SVGs, PDFs, Maps, to web pages.

How to add the Embed component:

To add the Embed component to your designs:

• Click the Embed button

• Enter your Embed's URL in the Setup panel

Forms are the primary building blocks of any data heavy applications. With Budibase you can build rich, themeable forms to create and edit your data.

Overview

Forms are built up from 3 main component types - a form component, field group components and field components. It's important to understand the best component layouts for forms, so you can take advantage of features like embedding any other content inside forms, or using data bindings to link up your form to other components.

Embedding Non-Form Content

Forms can contain any content - not just field groups and fields - so you can easily nest any other components alongside your form components. The best way to achieve this neatly is to always put groups of fields inside a field group component, then you can simply include any other components inside your form, beside the field groups.

Validation

Form Building Blocks

Video Guides

Field groups are components which group fields together. They allow your fields to be neatly aligned with each other, and let you style you fields with consistent label positions.

Field Group Settings

Field groups are simple group components, so they don't have many settings.

Label Positioning

Each field component has a label associated with it, showing the name of the field. Field groups let you align your labels for multiple fields, to keep them looking neat and consistent. There are 3 different options for label positions - left aligned, right aligned and above your field.

Generating Fields Automatically

Field groups have a powerful function which can save you a lot of time when working on forms - they let you reset them, which automatically populates them with all the fields in your form schema. This means you can generate a full form in one click, or you can add in missing fields if you change your schema.

When you select a field group component in the builder, you'll be able to press "Reset Fields" in the settings panel to perform this function.

Each field component represents a single field in the form. There are different component for every data type - e.g. a text field, an options picker or a checkbox.

Field Settings

All fields have a field and a label setting. The field is the name of the field, or property of the schema. This can be free typed or, if a schema exists on the form, selected from a list. There are unique components for every type of data, and if your form has a schema then you'll only be able to choose field names which fit the particular type of component that is selected. The label setting is the label that will be displayed beside or above your field. Most fields also have a placeholder setting to control the text displayed when the field is empty.

Some field components for certain data types may have other settings, but in most cases this table is an exhaustive list.

Custom Fields

Whether your form has a schema or not, you can always add custom fields that don't exist in the schema by free typing the name of the field. Data bindings will always reflect the names of all the fields in your form - so even if you don't have a schema on your form, you'll be able to bind to any of your fields.

Often you want to run automations or update data when a user presses a button. This is what actions are for. To define your actions, click the Define actions, a drawer will appear where you can add, or remove actions tied to this component.

The list of available actions are listed below:

• Save Row

• Delete Row

• Navigate To

• Execute Query

• Trigger Automation

• Validate Form

• Log Out

• Clear Form

Save Row

Saving a row can mean two things, updating or adding a new row. Depending on what you want to do you will have to structure your code differently.

If you're adding a new row the easiest way is to add a Form component. Once you've set that up correctly you add a button to it and select the Save Row action. You then select your form and the table you want to save it to. That's it. An example of how it might look is below.

Updating a row can be done in a number of different ways. If you have a structure containing a Data Provider and a Repeater, selecting the repeater as your Data Source will make it so you can correctly get the values from the specific row. To change a field you then take advantage of the add column button that is at the bottom. Click it, select the field you want to change and type in the value you want to change it to (or use a binding). A descriptive image of this is shown below:

Delete Row

This action is used to delete rows from your data source. It's used much in the save way that you would when updating a row.

Navigate To

Use this action if you want to go to another page. This can be used to navigate back to a dashboard after adding a new row to a table among other things.

Execute Query

The queries that you have created in the backend can be triggered via this action.

Trigger Automation

If you have set up an automation you can use this to trigger it.

Validate Form

Whenever you want to add a new row to a table you might find yourself wanting to validate the data before you send it off. This action is perfect for such use-cases.

Log Out

If you want to log a user out, you can use this action

Clear Form

An action that is used when you want to clear a form.

A lot of the time you want to change the state of some component when certain conditions are true or false. This might be changing a color from red to green, showing or hiding a component. You will find the condition settings at the very bottom of the settings panel of your components.

Adding a condition is simple. Once you click the settings button a drawer will pop up and you will be able to add, edit or remove your conditions. It will look something like this

Adding a condition

To add a condition, simply click the Add condition button. As explained above, you can choose wether to Show, Hide or Update setting. Depending on what you choose you will be presented with different options. They will all contain settings for comparing some value against another.

An example

In the example we're going to discuss we have a simple backend table that contains three records. It looks like this:

As we can see, there are four fields, Company, Due Data, Value and Paid. In the Design section we have designed a simple interface showing each of our invoices in rows. It looks like so:

It would be great if the Pay Invoice button was in a disabled state if the invoice has been paid. So let's go ahead and add a condition to do just that!

Select the button component in the tree view on the left. Open the conditions drawer and select Update setting and then pick the Disabled setting in the dropdown. Make sure the checkbox is checked. We then need to figure out which field we want to check. In our case it's found under {{ Repeater.Invoices.Paid }}. This will of course differ depending on the structure of your application. If you click the little lightning bolt icon you will be able to see which fields are available for use. Now we just make sure that it equals TRUE. Hit save, and that's it!

Now that we have this condition set up we might also want to change the text of the button to say "PAID". To do that, simply click the copy button and change the setting to "text". Change the text to "PAID" and hit save.

And here's the end result.

The Form component is the top level component of forms. All field groups and fields must be placed inside a form, and they won't work outside it.

Form Settings

Forms only have a few simple settings.

Form Schemas

Forms have a Schema setting which is optional. The schema for a form can be a table, view, relationship, query or "custom". A custom schema means that there is no backing data source schema.

Choosing a form schema has the following advantages:

• When adding fields, field names can be chosen from a dropdown rather than being typed

• Field validation is automatically added to match the schema

• If you want to create rows in a table using your form data, you'll need to choose the correct schema for the table you'll be saving your data to

• Fields will be able to automatically prevent you entering an illegal field name for a certain data type

• Form components can be automatically generated to match the schema

App state is a generic store of values that can be used to easily pass values around and persist them between navigation and page reloading.

Unlike other bindable values, App state values can be set and used anywhere in your application. Nesting is not required. To set an app state value you can use a new action called Set Value in the actions drawer. There are two types; Setting or Deleting a value. When selecting a key the combobox will show all the existing app state values across your application. If you want to add a new one you simply type a new one into the box. After this, you can enter any arbitrary value into the value input field. In addition to static values, you can also use bindable values here.

Persisting values

If you wish for the values that the user has selected to persist you can select the Persist this value checkbox beneath the key/value fields. Doing so will save the value in the users browser using the localStorage API.

Deleting values

Deleting a value will delete it permanently and will also override values that are persisted.

Referencing state values

Once you have created a value you are free to bind to it across your application. All values live under the State top level bindable value and are visible in the bindings drawer.

For example, To get the value in the example image above you would enter {{ State.isPersonal }}.

Pulling data from your tables and displaying it is a critical part of any data-driven application. We've made this as simple as possible, by using a single component to control fetching, filtering and sorting your data. This component is the data provider component.

Overview

A data provider component fetches data and provides it to all child components. Any child components which take in data to display have a simple setting for which data provider is providing their data. You can hook up as many components as you like to the same data provider, and they'll all be in sync with each other.

Data providers have settings to control filtering, sorting and pagination. Because all of these data settings are handled by the data provider, it keeps all components as purely presentational. You can update the source of your data provider and your whole dashboard will instantly reflect an entirely different table!

Fetching Data

To start off, add a data provider component to your app. It usually makes sense to have this quite high in your component tree, as anything that needs the data it will provide needs to be nested inside it. In the settings panel, choose the source of your data. This can be an internal table, a view, a relationship or an external data source query.

Displaying Data

Lets say we'd like to display all our sales records in a table, and also in a chart. All we need to do is add both components, and configure the data provider settings. For the chart we'll also need to configure some other chart-specific settings, but the table will show all our records instantly.

Our component tree should look something like the following.

Our application should now be displaying our data in both components!

Budibase uses the Spectrum design system by Adobe. Included are four base themes; Lightest, Light, Dark, and Darkest.

If you are not satisfied with the base themes you can customize the options below:

• Primary colour - used for the action variant on buttons, form fields (icons, checkboxes, radios, borders, and date pickers), icon colours, etc.

• Primary color (hover) - like the previous one but when the element is hovered.

• Navigation bar background color: the background color of your navigation bar. This also includes the drawer menu when on mobile.

• Navigation bar text color - the text color of your navigation bar.

For much more detailed documentation on all the handlebars helpers budibase provides, you can find the entire suite of budibase handlebars helpers here in the README of this repository:

There are a number of places that bindings can be utilised throughout the Budibase Builder such as:

1. External data source queries - when building a query it is possible to utilise Handlebars syntax to specify where parameters should be inserted, e.g. SELECT * FROM users WHERE username = {{ value }}

2. The value of components in design - the values of most components in the design can be populated with bindings; anywhere that a value in the components setting has a lightning bolt next to it a binding can be inserted. Clicking the binding button (the bolt) will open the binding drawer.

3. Automation steps - automations have the ability to make use of data from previous steps, this can be found in the binding panel; opened in the same manner as with the design bindings.

When making use of bindings it is possible to manipulate the data using the Budibase Handlebars helpers, these allow performing calculations, carrying out some basic logical comparisons and some array/string functions. The full list of options available is as follows:

Below is a video showing some of the capabilities of Budibase bindings in the design panel - showing how to add a repeater to make use of table data and then displaying some date values as well as carrying out some complex string manipulation.

Tips and tricks

It is important to remember than Handlebars does allow quite complex statements, which can make use of comparative logic (especially with our comparison helpers). Below we've detailed a few tips which should help you get started with bindings and Handlebars syntax.

Chaining helpers

Handlebars allows chaining helpers together to create quite complex statements - for example if I had the string "Username: Michael" and I wanted to just get the name I could do the following:

{{ last ( split "Username: Joe" ": " ) }}

In the example we split the string by the colon and space in the middle, then get the last element of the array produced by the split helper. Chaining helpers simply requires wrapping each layer of helpers with parentheses, although it is important to remember parameter order, for example if we had the string "My name is Joe Bloggs" and we wanted to get the string "Joe Bloggs" we would do the following:

{{ join ( after ( split "My name is Joe Bloggs" " " ) 3 ) " " }}

Take note with this statement of where the "join" and "after" last parameters are positioned, here we are splitting the string into an array by the spaces, then selecting the elements in the array after index 3, then finally re-joining the string with a space again.

Iteration

A powerful feature which can be utilised with Handlebars is the ability to iterate over an object or array. This can be extremely useful when paired up with data sources, for example if you had a DynamoDB table which contains JSON you might want to do the following:

{{#forIn Query 1.object.json}}
  property: {{@key}} - value: {{.}}
{{/forIn}}

This would print out the key and value of each property in the JSON object retrieved from the query - notice the use of the {{ @key }} and {{ . }} these are specific to the forIn helper. It is important to note that the iteration functions do require the input to be of the correct type, forIn requires an Object and forEach requires an array - the forEach helper also requires that each element of the array contains an object so that the properties of the object can be referenced, for example:

{{#forEach Query 1.array}}
  username: {{ username }}
{{forEach}}

In the example above it is assumed that the Query 1.array property is an array consisting of objects that contain username property.

Conditionals and comparisons

Handlebars is capable of carrying out logic when running a block, this is a core component that can be used to produce more conditional outputs. An example of this might be pulling information from an external data source, which has information about a customers total spending, we might do something like:

{{#if ( gte Query 1.Customer.spending 1000 )}}
  Thanks {{Query 1.Customer.name}}! We value your patronage.
{{else}}
  Hi {{Query 1.Customer.name}}!
{{/if}}

As you can see from this example we can wrap an statement in an #if block which allows us to produce a specific output when a condition is met. We have also made use of the gte helper which checks if the first property is greater than or equal to the second property. Chaining together a few different helpers and then finishing with a comparison can allow us to perform some very specific logic. We can also make use of regex to perform conditional logic, as such:

{{#if ( test "hello there" (toRegex "there"))}}
  Over there!
{{/if}}

We can use the test helper to run a regex expression against a string, this regex can come from the toRegex helper or it can be directly input as a string; or even a property of a table, query or automation step!

Budibase automations gives you the ability to build your backend logic into your Budibase applications. Your apps need to be able to handle processes that would have previously needed to be carried out by hand, like sending emails when data is updated in a table or deleting records when a particular conditions are met. Automations can also be used for integrating with external platforms and services, for example if you already have web services that are deeply integrated into your processes then automations can be used to receive or send data automatically between the two systems.

Once configured your automation will run as part of your app in the Budibase hosting platform making this a backend process that will run at any time when triggered. We will also be supporting automations as part of our self-hosted offering once this is made available.

Getting started

To get started with Automations click into the Automate tab in the builder, from here you will see the button to "Create new automation", this will ask you for a name for your automation - you're now ready to get started.

The next sections will cover the three major components of an automation, triggers, logic and actions. It will also cover the contextually aware inputs of the system, allowing chaining of the various automation steps together.

Sometimes it is necessary for your automation to make decisions as part of the process, for example if you wanted to send an email to a customer when their order enters the shipped state then you would need a logical step to handle this. An automation can have as many logical steps as you require, if you wish to filter against multiple different outputs from previous steps then this can be done with multiple filters.

Currently there are two main ways that logic can be executed in an automation:

1. Filtering against a specified field, with a particular operator and value to compare against

2. Delay, waiting a period of milliseconds before continuing

Our filter currently can handle checking a single input value against a single, if the condition is not met then the automation will stop execution, if two separate paths are required then two different automations can be used.

In this section we will cover the the three main components of an automation and how they are used together to create the automation processes your app requires.

Once you have created a new automation you will find a panel on the left hand side of the builder, listing steps that can be added, initially only the list of triggers, once this is picked you will be presented with a list of logic and action steps.

In the following pages we will cover the three step types:

Below is a quick overview of setting up a few steps as part of an automation.

Static Filtering

Once you have added a data source to your dataprovider component you can access the filter drawer by simply clicking on it. In the drawer that comes up you can add an expression. This is where you select a column you want to filter on. Let's say you wanted to filter out all rows with a price greater than 100 - you would select the appropriate column, select "More than", "value" and then type in 100. You are not limited to just one expression, you can add as many as you like.

Filtering data from the front-end

Often you will find yourself wanting to let the user filter the data on the front-end. This can be achieved as well but requires a bit more work. To get started you will need a Form component. Select the schema you want, most often it will be the same thing you select in the data provider. Inside the form, put a Data Provider component as well as a field of your choice, an easy one to get started with is the Number Field. On the field component you select the column you want to filter on. In the example below we'll use the unit price.

In the data provider, select the define filters button. Next add an expression and select the same Unit Price that you selected for the number field component, "More than" and "Binding". Select the lightning bolt icon to the right and select the number field from the list of bindings that comes up. After saving your users should now be able to filter the data themselves.

Video tutorial with two option pickers

Each automation must have a single trigger step, this is essentially a watcher - waiting for a particular condition to be met at which point the process will kick off.

Currently there are three main ways that an automation can be triggered:

Actions are the core of automations, these can carry out updates on a table, call to an external service, send emails and so on. We have built our action system to be easily extensible so actions can be added to the system at any time! Your automation can have many actions, allowing you to perform many different tasks as part of a single trigger.

Below is a few examples of actions that exist today however there may be many more when you look in the builder, to get a full list install the builder and check it out!

2. Update row, can be used to update a row which was triggered upon

4. Send an email, as it suggests, send an email based on the specified inputs

OpenID Connect (OIDC) is a simple identity layer built on top of the OAuth 2.0 protocol, which allows clients to verify the identity of an end user based on the authentication performed by an authorization server or identity provider (IdP), as well as to obtain basic profile information about the end user.

Setup

To enable OIDC for your IdP follow the setup steps below.

Configure your IdP

Any provider that supports the OIDC protocal can be integrated into Budibase, you may even implement your own.

Guides on how to setup some of the most common providers can be seen below:

See also:

Callback URL

• During your configuration you will need to enter the Callback URL for your Budibase installation.

• For example: https://{your-budibase-host.com}/api/admin/auth/oidc/callback

Configure OIDC in Budibase

To configure an OIDC integration in Budibase visit the Auth section of the builder.

Fill in the following options from your IdP:

• Config URL

  • For example: https://{your-identity-provider.com}/.well-known/openid-configuration

• Client ID

  • Your unique ID issued by your IdP

• Client Secret

  • Your unique secret issued by your IdP

Save the configuration to enable OIDC on your login page.

Customize your login

Use the login configuration options to customize the OIDC login button.

Fill in either of the following:

• Name

  • The name on the login button. This will be substituted at Sign in with {name}

• Icon

  • The icon on the login button. Choose from:

    • One of the default icons

    • Upload a custom icon

Important information

Some additional details on the OIDC integration are highlighted below.

User provisioning

Unlike the Google integration which requires a local user account to exist in advance, OIDC users are created in Budibase automatically when they log in for the first time. It is important that only the users you wish to access Budibase have been assigned to the application configured in your IdP.

You may still use email onboarding to create an account for a user in advance, provided the email matches the user's email in your IdP.