# Platform Overview
Welcome to Servoy!
This guide will provide an introduction to the platform and key concepts.
## What is Servoy?
Servoy is a comprehensive, low-code platform to build, deploy and manage core systems and enterprise-grade applications. It combines the speed of low-code with the level of control provided by traditional tooling.
### Who uses Servoy?
Servoy is primarily used by enterprise application teams and independent software vendors (ISVs). Unlike many low-code platforms, Servoy caters directly to IT users and professional developers. This is because Servoy provides standards-based, open-source tooling in an extensible, comprehensive low code platform.
### What can be built?
Servoy developers build applications for the browser, but also mobile devices, native desktop and headless automation. The platform enables specialized user experiences, intricate workflows and powerful business logic. Developers can build both systems of record and systems of engagement that interoperate and serve many users across different devices and environments, at scale.
## How Does it Work?
The following are a few key concepts that drive the developer experience.
### Data Connectivity
Servoy applications are inherently data-connected and data-driven. Developers can connect to any database, web-service, flat file or legacy system. Servoy works particularly well with relational database systems, providing enhanced capabilities for connecting, querying and updating databases. Developers can blend data from many sources, quickly build data-bound user interfaces and easily execute logic against their data models.
### Visual Modeling
The platform provides visual modeling elements to simplify development including data modeling, entity design, business objects, UI design, navigation and event routing. This greatly simplifies complex applications.
### Scripted Logic
Servoy embodies the idea that a great low-code platform should provide a great coding interface to increase productivity and control when application logic is needed. Servoy provides a JavaScript engine and a catalog of self-documenting APIs to solve any problem. Moreover the platform includes the tooling to make the job easy, such as code completion, examples, debugging and more.
## Platform Components
The following is a summary of the basic components of the Servoy platform.
### Servoy Developer
Servoy Developer is the integrated developer environment (IDE) where most of the development is done. Servoy Developer provides all of the tools to build and debug applications in a single package, including visual editors for modeling and UI design, a robust code editor and debugging tools.
### Servoy Core
The core consists of a design-time object model and the developer API. The object model contains all the design-time elements in the application, including data sources, business objects and forms. The developer API includes a catalog of packages for many common runtime operations.
### Servoy Extensions
The Servoy platform uses an open-architecture design and provides extension points throughout the stack. By default, the platform ships with many UI components, plugins, modules and themes. Developers can also extend the platform to solve any challenge. Servoy Developer includes the Package Manager, which can be used to include the following extensions in any project.
#### UI Components
The Servoy platform includes a comprehensive catalog of UI components. These range from common input controls to specialized components for data visualization, document editing and more. UI components can be assembled in the form editor, a drag-and-drop interface to design the UI. Developers can also include 3rd-party or custom components in their projects.
#### Plugins
Servoy's toolkit includes a scripting interface to control application logic. Code is written using the core developer API and plugins for specialized logic. The platform ships with a large catalog of plugins to handle common programming tasks, such as email, http, file i/o and much more. Developers can also include 3rd-party or custom plugins in their projects to meet any integration challenge.
#### Themes
At a fundamental level, Servoy applications are styled using CSS/LESS. However developers do not need to be proficient in these technologies. Themes provide a higher-level abstraction to simplify styling, making applications consistent and easy to maintain.
#### Modules
The Servoy platform is designed on the principle of composable architecture and applications may also become modules, encapsulating business objects and code to be reused in other applications. Servoy ships a number of general and specialized modules and developer may build their own modules to use best-practices in application design.
### Servoy Application Server
Servoy provides an application server which brokers data source connections and manages all the client sessions. The server, applications and modules may be deployed together in a simple self-contained docker image or war file. Applications may be deployed in any of the following client types.
#### NG Client
The NG Client is the primary runtime of the Servoy platform. It is a light-weight web application (HTML5, CSS and JavaScript) and runs in any modern browser. It implements a model-view-controller (MVC) design.
#### NG Mobile
Responsive web applications built in Servoy may be deployed through the NG Mobile client wrapper for iOS and Android devices. Additional plugins give developers access to device APIs, such as camera, GPS, push notifications and more.
#### NG Desktop
Servoy applications may be deployed through the NG Desktop client wrapper for Windows, Mac and Linux devices. Additional plugins give developers access to desktop APIs, such as filesystem, local hardware, printers, scanners, etc.
#### Headless Client
Some applications are not meant to have and end-user or a UI. For this purpose, Servoy provides the Headless Client, which can be used for automation jobs, parallel processing and REST API generation. All the same tools and concepts apply, except for UI design.
### ServoyCloud
Applications built in Servoy can be deployed in any environment; on-premise, self-hosted, public or private clouds. In addition to the tools to build and deploy applications, Servoy provides specialized cloud infrastructure to automate software delivery and high-availability (HA) production environments to host, monitor and manage production applications.
#### Delivery Pipelines
ServoyCloud provides a flexible, low-touch DevOps control center to manage and automate the software delivery lifecycle and maintain quality.
* Revision Control (Git) Integration
* Build Automation
* Quality Control and Test Automation
* Artifact repositories
* Docker Orchestration
#### Production Environments
ServoyCloud provides specialized infrastructure and production environments to remove the burdens of hosting and provide stable, scalable and secure applications anywhere on the planet. The following are just some of the specialized components of ServoyCloud production hosting:
* Full-stack container monitoring and log management
* Application performance monitoring
* User insight and analytics
* Zero-downtime deployments
* Auto-scaling pods and infra based business hour rules
* Full backup/restore and disaster recovery scenarios
* Auto-renewal of keys and certificates
# Get Servoy
This guide will walk you through how to begin using the platform
This guide will explain how to get access to the Servoy platform
Servoy is a comprehensive, low-code platform to build, deploy and manage core systems and enterprise-grade applications. It combines the speed of low-code with the level of control provided by traditional tooling.
## Register
The first step is to [register](https://admin.servoy-cloud.eu/solution/svyCloud/index.html?a=registration) for your free ServoyCloud account. After you register and confirm your email address, you can log into ServoyCloud to continue.
## Download Servoy Developer
If you have already registered, log in to ServoyCloud and select the option "Download" from the main menu. Choose your operating system and Servoy version. It is recommended to use the "CURRENT" or "LTS" builds.
Once the download has completed, you are ready to install the Servoy Developer IDE to [get started](/guides/get-started).
## Installation
Below is a step-by-step guide to installing Servoy Developer.
### Windows, Mac and Linux
Installing Servoy Developer is easy and depending on your operating system, your experience will vary. For **Windows** and **Mac OS**, you will get an installer executable, `.exe` and `.dmg` respectively. Open this file to begin the **Installation Wizard**.
For Linux (or cross-platform) installation, you will receive a `.tar.gz` distribution. Simply extract it to your desired location; no installation wizard is needed.
Servoy Installation Wizard for Windows or Mac OS
### Choose Installation Directory
Choose a directory on your local file system where you would like to install Servoy Developer.
{% hint style="info" %}
Each installation is fully stand-alone. This means that you can install as many copies of Servoy Developer as you want
{% endhint %}
## Run Servoy Developer
You have the option to run Servoy Developer at the end of the Installation Wizard. You can also run Servoy Developer at any time by opening the application installed in the following location, relative to your installation path.
`//developer/servoy`
### Select a Workspace
When you start Servoy Developer, you will be prompted to choose a workspace[^1] directory. This will be your working directory for your first project and can be any location on your file system.
{% hint style="info" %}
Don't be shy. You can have as many workspaces as you want and you may easily switch between them.
{% endhint %}
You have the option to use your selection as the default. If you select this, you will not be prompted again to choose your workspace when starting Servoy Developer.
### Install the Sample Database
When you first start Servoy Developer, you will be prompted to install the default, sample database. This is a PostgreSQL database with sample schema and data. It is highly recommended to allow the default option here, as the sample is useful for tutorials and examples.
{% hint style="info" %}
If you already have experience or you are sure that you do not want to install the Sample Database, you may choose **advanced settings** and skip the installation of the database, the sample data or both.
{% endhint %}
Nice work! if you have made it this far, you are ready to begin the [Get Started](/guides/get-started) tutorial.
[^1]: A [workspace](/reference/servoy-developer/project-file-structure/workspace-folder) is a working directory for a Solution or set of solutions. Servoy Developer will have only one workspace folder open at a time. However, you can have many workspaces on a single machine and can switch between them easily.
# Get Started
This guide will help you to quickly build your first Servoy application
In this guide, we will build a small CRM-like application using the example database that ships with Servoy Developer. This guide is meant for beginners learning the Servoy platform.
# Chapter 0
Setup and Requirements
Before we get started, it's important to make sure that your environment is properly setup to work on this tutorial.
## Setup ServoyCloud
To start creating applications, you must first register for a free ServoyCloud account and then create your namespace. Without a namespace, you cannot create, manage, or deploy applications to the cloud.
### Create a ServoyCloud account
The first step is to [register](https://admin.servoy-cloud.eu/solution/svyCloud/index.html?a=registration) for your free ServoyCloud account. After you register and confirm your email address, you can log into ServoyCloud to continue.
### Create a namespace
Log into the [Cloud Control Center](https://admin.servoy-cloud.eu/) and from the home page, click on the button `Start Cloud Setup`.
See namespace [setup instructions here](/reference/servoy-cloud/cloud-control-center/home/setup-namespace) or follow the on-screen instructions.
After setting up your namespace, proceed with installing the developer and checking out your application.
{% hint style="warning" %}
Namespace setup may take a few minutes.
{% endhint %}
## Install Servoy Developer
It's recommended that you [download and install](/guides/get-servoy#download-servoy-developer) the latest version of Servoy Developer.
{% hint style="info" %}
If you have an existing copy of Servoy Developer that you want to use, be sure to switch into an empty workspace. This will ensure that you don't corrupt your tutorial with files from an existing project.
{% endhint %}
## Log in using Servoy Developer
Once you have downloaded and opened Servoy Developer, use the Servoy Cloud Control Center credentials to log in.
Servoy Developer login dialog using Servoy Cloud credentials
{% hint style="info" %}
If the login dialog is closed without logging in, open it by clicking the Servoy icon in the bottom right corner of Servoy Developer.
{% endhint %}
## Select Servoy Cloud Application
After successful sign-in, a dialog box will appear prompting you to select your application.
Check out application dialog box
After making your selection, the source code will be automatically checked out into your local workspace.
{% hint style="info" %}
If the dialog does not show, switch into an empty workspace. This will ensure that you don't corrupt your tutorial with files from an existing project.
{% endhint %}
## Include Example Data
The subsequent chapters of this guide rely on the example database that should have been installed by default during the installation process. If for some reason, you do not have the example database, then you must reinstall Servoy Developer and be sure to include example data.
To confirm that you have the example database, look at the Database Servers node in your Solution Explorer panel. You should see a database called `example_data`.
{% hint style="success" %}
Excellent! Now you are ready to begin adding features to your first solution.
{% endhint %}
# Chapter 1
Create your first form
## Overview
In this chapter, you will create your first Form in the new Solution, connect it to a data source and add some fields and labels.
### Key Concepts Covered
* **Forms**
* **Components** and data-bound fields
* **Value Lists** and **Type-Ahead** lookups
* **Labels** and data-driven text
* **Formatting** (Dates)
* **The NG Client** to preview and test
* **Publishing to Servoy Cloud**
## Create a Form
Create your first form by right-clicking the forms node in the Solution Explorer and select `Create New Form`.
Enter "orders" for the name. Select a datasource. Choose the `orders` table in the `example_data` database and click `OK`.
Choose the default values for the remaining properties and click `Next`.
### Place Data Providers
The next section of New Form Wizard is to optionally place data providers (data-bound fields) on the form. Components can be placed on a form at any time, but in this tutorial, we'll take advantage of this wizard, when creating the form, to quickly get some fields an labels.
You'll see a list of data providers for the `example_data.orders` data source. We will choose from this list in a moment, but first, click the `Advanced Configuration` button to get more options.
Here we can configure a few options about which components to place for different data types, as well as default sizes and spacing. We can also choose to place labels and more.
Choose the following values to control how the fields are placed.
Next, you are ready to choose the data providers that will be placed on the form. Choose the following data providers and click Finish.
* `customerid`
* `employeeid`
* `orderdate`
The Form Editor should open and you should see a form having the fields that you selected.
## Set the First Form of your Solution
To see the form `orders` as the first form in your solution, you must set it in the firstForm property of your solution.
To set your solution `firstForm` property, click on the solution name in the Solution Explorer. In the properties view, this will show all the properties of the solution you just clicked.
Double click on the property `firstForm`, select the `orders` form and click the `Ok` button to save your changes.
{% hint style="success" %}
The first form of the solution is now set and you are ready to run your solution.
{% endhint %}
## Run your solution
### Run your solution locally
Servoy Developer comes with a built-in instance of the **NG Client** to preview, test and debug your solution at any time during development. To launch the client, click the icon.
Your solution will open in the default browser and you can see that the form is populated with data from the first record in the `orders` table.
### Run your solution on Servoy Cloud
Besides viewing the solution locally, you can also publish it to Servoy Cloud and view it in the browser, as a web application.
To publish your solution to Servoy Cloud, click the icon.
{% hint style="warning" %}
You must click the publish button every time you want to update your cloud application.
It may take a few minutes for changes to take effect.
For immediate results, run your solution locally.
{% endhint %}
To view your web application, use the link generated when you created your namespace with the format `https://yoursolution-dev.yournamespace.servoy-cloud.eu` or using the Cloud Control Center:
1. Login into [Cloud Control Center](https://admin.servoy-cloud.eu/) using the credentials set up in [Chapter 0](/guides/get-started/install-servoy-developer#setup-servoy-cloud)
2. Using the side menu, go to `Project Overview` > `Applications`
3. Click on your application
4. Click the button `Launch in ServoyCloud`
{% hint style="success" %}
**Nice Work!** It may not look like much, but you've created a web application, which connects to and queries your database and loads data in a form. Let's keep going and enrich the form a data labels and value lists.
{% endhint %}
## Add a Value List
In this step we will add a Value List to allow the user to choose values from other database tables. The form currently displays two fields, `employeeid` and `customerid`, both of which are foreign key columns to related tables. Therefore, the current display of the raw values is not so nice.
Let's use a `Value List` object to show more meaningful information about those foreign entities and allow the user to choose related records. To do this, we will delete the two fields and replace them with Type Ahead components, bind them to Value Lists.
### Place a Customers Type Ahead component
Start by deleting the `customerid` field (we'll leave the label). Select the component on the Form Editor and push the `del` key (or right-click the component and select `Delete`).
Locate the `Type Ahead` component in the `Pallet` and drag it onto your form, positioning and sizing it accordingly below the customer ID label.
{% hint style="info" %}
You can quickly filter the Pallet by typing in the *Search* field at the top.
{% endhint %}
Place a Type-Ahead component and bind to a new Value List
#### Set the Data Provider
In the component Properties Editor, double-click the `dataProvider` property to open the Data Provider Chooser. Select the `customerid` column.
#### Set the Value List
In the component Properties Editor, double-click the `valuelist` property to open the Value List Chooser. Click the button to Create New Value List. Enter the name `customers` and click `Finish`. (Click `OK` to dismiss the Value List Chooser.)
### Create a Customers Value List
Now that you have created the Customers Value List, you are ready to edit its properties in the Value List Editor. This editor should have opened upon creation of the new Value List.
#### Set a Value List Type
Select the Value List type by choosing the `Table Values` radio option. This option specifies that the values will be queried from a data source table.
#### Set the Data Source
Click the `...` button to open the Data Source Chooser the data source for the Value List. Select the `example_data.customers` data source and click `OK`.
#### Select the Display Value
Choose the `companyname` data provider to "show in field / list". This is the value that will be used to render instead of the real value.
#### Select the Real Value
Choose the `companyid` data provider to "return in data provider". This value will not be displayed. Instead it is the value that will be stored in the target data provider / field.
Click the Save All button (or `ctrl+shift+s`) to save all your editors. Navigate back to your NG Client running in the browser and preview the change.
{% hint style="info" %}
If you leave your browser tab open while you are working in Servoy Developer, your changes will just be pushed to the running client when you save. You don't even have to re-launch it! (Keep in mind that certain things will require a re-launch, such as variable initialization, onLoad events, etc)
{% endhint %}
Preview of the Customers Value List
You can see that the `customerid` is now hidden and the `customers.companyname` field is shown instead. Moreover, when you edit the Type Ahead field, your results will match on records in the table based on the `companyname` but the correct value will be stored in the `orders.customerid` field.
### Create an Employees Value List
Let's create one more Value List for the employee connected to the order. This time we will create the Value List first then bind it to the `employeeid` field.
In the Solution Explorer, right-click the ValueLists node and select Create Value List. Enter the name `employees` for your next Value List. This will open the new Value List in the Value List Editor.
{% hint style="info" %}
Value Lists are completely reusable. Define them 1x and use them *anywhere* in your solution. They can even be referenced in your scripts!
{% endhint %}
Create Employees Value List
Follow similar steps as you did for the customers Value List. Set the **data source** to be `example_data.employees`. This time we will set multiple **display values**, using both `firstname` and `lastname` for the display. Use `employeeid` for the **real value**.
Properties for employees value list
### Add the Employee Type Ahead
Delete the `employeeid` Text Box from the form and similar to the customer field, drag a Type Ahead component from the pallet to replace it. Set the `dataProvider` value to `employeeid` and this time, when you set the `valuelist` property, you will choose the `employees` Value List that we just created. Save your editors and preview your changes in the NG Client.
Preview of Employees Value List
You can see that because we specified *two* display values, the employees value list shoes both `firstname` and `lastname`. Moreover the lookup will query *both* columns to match values!
## Working With Labels
In this section, we will quickly edit some of the labels that we have already placed, then we will explore how to add more data-driven text.
### Edit Label Text
The labels for each of the fields defaulted to the name of the database column, which is rather ugly. Let's quickly update those labels to something nicer.
Update label text by double-clicking
To edit the content of the label, simply double-click the label in the form editor and begin editing the text.
### Adding a Data-Driven Label
In Servoy, any text can be data-driven and localized. Let's place a label that shows some plain text mixed with **merge tags**.
Place a data-driven label
1. Drag a Label component from your pallet onto the form.
2. Select the `text` property of the label click the `...` button to open the [Text Property Editor](/reference/servoy-developer/object-editors/text-property-editor).
3. Enter the literal value "Order #" then use the data provider chooser to append the `orderid` column to the text, giving the value: `Order #%%orderid%%`
4. Edit the `styleClass` property, selecting `h2`. This will change the style of the label. (We will cover more on styling in a later chapter)
5. Save your changes and preview the results in the NG Client. You can see that the `%%orderid%%` tag was merged with the data value from the record.
## Format a Date
In the final section of this chapter, we will see how to format data values, in this case, we'll set a format for the `orderdate` field.
1. Select the `orderdate` field on the form and select its `format` property, then click the `...` button to open the [Date Format Editor](/reference/servoy-developer/object-editors/date-format-editor).
2. Edit the Display Format. Enter `yyyy-MM-dd` (or a format of your choice). This will format the value when it is being displayed.
3. Select the `Use as mask` option for editing. This will allow the user to just enter the value digits and not the separator.
4. Click OK and save your form editor and preview in the NG Client. You can see that the date is formatted and the user can enter with masking.
Format a date field
# Chapter 2
Create your first data grid and enhance your layout
## Overview
In this chapter we will add a grid component to the form to show all orders and allow the user to click through records. We'll add some related data and we'll learn about positioning components.
### Key Concepts Covered
* **Relations**
* **Data Grids**
* **Simple Positioning**
* **Date format** (review)
## Create a Relation
Let's get started by creating your first Relation. We're going to create a relation from the `orders` table to the `customers` table.
The Relation Editor; creating the relation orders_to_customers
1. From the [Solution Explorer](/reference/servoy-developer/solution-explorer), right-click the "Relations" node and select "Create Relation". This will open the [Relation Editor](/reference/servoy-developer/object-editors/relation-editor).
2. Set the `Source` by clicking the `...` button to open the Data Source Chooser. Select `example_data.orders`and click OK.
3. Set the `Destination` by choosing `example_data.customers`
4. Create one relation item where `orders.customerid` `"="` `customers.customerid`
5. Save the editor.
{% hint style="info" %}
Notice you don't have to specify the relation name. The editor will always suggest `source_to_destination`, in this case **orders\_to\_customers**. This is a good convention to follow for ordinary relations.
{% endhint %}
## Create a Data Grid
In this step you will create your first **Data Grid** and position your components more precisely using **Simple Positioning**.
### Re-Position your Fields and Labels
We are going to add a Data Grid to the left side of the form, but first weEdit need to make some space for it, let's move our fields and labels out of the way.
Edit the CSS Position Left property
1. Select all your components by click-dragging a box around them. Now you can edit their shared properties in one go.
2. In the **Properties Editor**, expand the `cssPosition` property and edit the left property, clicking the `...` to open the **CSS Position Property Editor**.
3. Choose the `calc` option and set it to `25% + 10px`. This will position the left edges of the component 25% of the total width of the form, plus an additional 10 pixels.
### Place the Data Grid
Now we are ready to place the Data Grid so the user can easily click through multiple order records.
Place a Data Grid
1. From the pallet, drag the Data Grid component on to your form. The [Grid Columns Configurator](https://github.com/Servoy/gitbook/blob/master/guides/get-started/broken-reference/README.md) will immediately open.
2. You will see the `orders_to_customers` relation that you have already created. Expand it and choose the `companyname` data provider.
3. Choose one more data provider, `orderdate`.
4. Edit the Header Title property, entering `Customer` and `Date` (These will appear in the column headers) and click OK.
#### Adjust the Position
Let's adjust the grid's position, similar to what we did to the other components. Select the grid and edit the cssPosition property. Enter the following values.
* right: 75% (75% of the width of the form from the right edge)
* bottom: 10px (10 pixels from the bottom)
* left: 10px (10 pixels from the left edge)
* min-width: -1 (this means that no minimum will be enforced)
#### Set the Date Format
Select the date column on your grid. In the **Component Properties Editor**, edit the `format` property. Enter a value of `yyyy-MM-dd`. This will format your date column year-month-day.
Save your editors and preview your changes in the NG Client.
Preview Data Grid in NG Client
You can see that the grid is showing the related customer info with the formatted date. It occupies 25% of the form's width and it can be used to navigate records in the `orders` table.
{% hint style="success" %}
The form's grid and fields are data-bound and the Servoy platform manages all the querying, caching and record selection for you. No code needed!
{% endhint %}
# Chapter 3
Add related data, calculated data and format numbers
## Overview
In this chapter, we will add the order details to show which products have been ordered. We'll create several new relations and a data grid. We'll add a calculated value and format a number to the localized currency.
### Key Concepts Covered
* **Calculations**
* **Formatting Numbers**
* **Value Lists** (review)
* **Relations** (review)
* **Data Grid** (review)
### Create a Relation
First let's create a new relation to set up our next data grid. We will create relations to the `order_details`table. (This is a review from the previous chapter, so please review that it you need to.)
### Orders to Order Details
Let's create a relation so that we can show all the details of a single order.
Relation Editor: orders_to_order_details
Create a new relation object. Select `example_data.orders` as the *from* data source. Select `example_data.order_details` as the *destination*.
{% hint style="info" %}
Notice that the Relation Editor correctly guesses the foreign key `order_details.orderid`. This is because it has the same name as the PK column in the source table.
{% endhint %}
## Place the Order Details Grid
Next, we'll place another Data Grid on the form, this time choosing a related data source.
Place Related Data Grid
1. When the Columns Configurator appears, click the `...` button to choose a different data source.
2. Expand Related Foundset to find your relation `orders_to_order_details`. Select it and click OK.
3. Now you will see the data providers for the `order_details` table. Choose the following data providers, set their title text and click OK.
* productid
* quantity
* unitprice
#### Position the Grid
Position your grid to take the remaining 75% of the width and stretch near the bottom edge. Set the `cssProperty` of the grid to the following values:
* left: calc(25% + 10px) This is the same value as the other fields and labels
* right: 10px
* bottom: 10px
Save your editor and preview the changes in the NG Client. You can see that as you select different order record, the related order details records of each order are loaded in the grid. However, this grid does not look great. Let's make it nicer by adding a product lookup and formatting the price.
Order Details Grid Preview in NG Client
### Create a Products Value List
Let's create a value list to show a nicer lookup on the product name for the product id foreign key. This will also help us when we make the grid editable.
Value List Editor: Products Value List
Create a new Value List with the following properties.
* Name: products
* Type: Table Values
* Data Source: `example_data.products`
* Display Value : `productname`
* Real Value: `productid`
Save the editor and attach the new Value List to the product column in the grid by editing the column's `valuelist` property and choosing the `products` Value List.
### Format the Unit Price
Next, let's make that Unit Price column look nicer by applying a Number Format.
1. Select the Unit Price column
2. Edit the format property and click the `...` to open the **Number Format Editor**.
3. Choose `¤#.00` for the Display Format
4. Choose `#.00` for the Edit Format (we'll make this grid editable in the next chapter)
5. Click OK and save your editor. You can preview your changes in the NG Client.
### Adjust the Column Widths
You may have noticed that the column widths are auto-sized, which is convenient. However, the quantity and the unit price are both reliably skinny values. Let's set a default width for these columns to leave more room for the product name.
1. Select the Quantity column and set the `max-width` property to `150`.
2. Do the same for the Unit Price column.
3. Save and preview in the NG Client.
Order Details Grid with Value list, formatting and column width settings
Notice your product name is displayed instead of the ID. The Unit Price is formatted with the localized currency, and while the product column stretches, the other two maintain a max-width.
## Create a Calculation
For the last exercise in this chapter, we are going to create a **calculation**, to compute the subtotal of an order detail record.
Create a Calculation
1. From the [Solution Explorer](/reference/servoy-developer/solution-explorer), locate your `order_details` table:\
`Resources > Database Servers > example_data > order_details`
2. Double-click to open it in the [Table Editor](/reference/servoy-developer/object-editors/table-editor)
3. At the bottom of the Table Editor, select the Calculations tab.
4. Click the `Add` button and name your calculation `subtotal`.
5. Select `NUMBER` as the data type and save. Then, click 'Open selected calculation' to open the script editor.
### Write the Calculation Script
In the script editor, you will see a JavaScript function stub called `subtotal`. Every calculation is a function that must return a value, in this case, you will simply multiply the quantity by the unit price. Enter the following.
```javascript
function subtotal()
{
return quantity * unitprice;
}
```
{% hint style="info" %}
When you edit code in a calculation, a number of objects, including other data providers are in scope. You can get code complete by typing `CTRL-SPACE`. This is helpful to find the names of available data providers.
{% endhint %}
### Add the Calculation to Your Grid
Now you may place your calculation on your grid, just like any other column.
Add the subtotal calculation to the grid
1. From the pallet, drag a Column onto your grid component
2. Double-click the `dataprovider` property to open the Data Provider Chooser
3. You will see a **calculations** node, expand it and select your `subtotal` calculation
4. Set the `headerTitle` property to "Subtotal"
5. Set the `max-width` property to `150`
6. Finally, set the display `format` property to `¤#.00`, as you did for the Unit Price column
Save your editor and preview your changes in the NG Client. You can see that the subtotal column displays the calculated results for each line in each order.
Calculation added to grid
{% hint style="success" %}
Calculations are called when they are displayed and referenced in your scripts. But they are also refreshed when data is changed. This means they are *always* up to date!
{% endhint %}
# Chapter 4
Working with data, scripted logic
## Overview
In this chapter you'll begin to work with data and connect some scripted logic to UI events. We'll make our Order Details grid editable, add a button and code to create a new order, create a more advanced calculation field and more.
### Key Concepts Covered
* **Editing Data**
* **Foundsets**
* **UI Events**
* **Scripted Logic**
* **Calculations** (Review)
## Make the Grid Editable
Let's begin by adjusting our Order Details grid to accept user input.
Set the grid column editType property
1. In the Form Editor, select the Product column on your Order Details grid
2. In the Component Properties Editor, set the `editType` propery to `TYPEAHEAD`
3. Do the same for the Quantity column, this type setting the property to TEXTFIELD
4. Repeat the step for the Unit Price column
Save your changes and preview the result in the NG Client. You will be able to double-click into the fields and edit them. Note that the subtotal calculation is not editable .
Preview the eidtable grid
{% hint style="success" %}
**Calculation Refresh**\
Try editing the Quantity or Unit Price column. You'll notice that the subtotal calculation is instantly updated when you change the inputs.
{% endhint %}
{% hint style="info" %}
**TAB Key Support**\
After you begin editing a grid cell, try tabbing through them with the TAB key.
{% endhint %}
## Create new Records
Now that we can edit all the data on an order, it's time to give the user the ability to add new records. Let's begin by placing a button for new orders and hooking it up to some code.
Place a button for new orders and create an onAction handler
1. From the pallet, drag a Button component to the form
2. In the Component Properties Editor, set the `text` property to "New Order"
3. Set the `cssPosition` property to have the button anchor right: `45,`**`10`**`,-1,-1,140,30`
4. Double-click the `onAction` property to open the **Method Selection Wizard**
5. Select the option to create a method in the form and give it a name: `newOrder`
6. Choose Create Private and click OK.
The newOrder method stub is created
The `orders.js` file opens in the Script Editor and the new method stub `newOrder` is created. The `onAction` event of the New Order button is handled by this method. You are ready to fill in the logic.
{% hint style="info" %}
Each form has its own `.js` file to manage the scripting for the form. This is where most event handlers and other UI logic will be implemented.
{% endhint %}
### Add the New Record Logic
Next, you'll add some code to create the record.
```javascript
function newOrder(event) {
foundset.newRecord();
}
```
Here you will use the form's **foundset** object, which manages all of the data access. Invoke the [newRecord](/reference/servoycore/dev-api/database-manager/jsfoundset#newrecord) method to create a new record object in the foundset.
{% hint style="info" %}
**Code Complete**\
Type `CTRL-SPACE` at any time to get code completion. You will also get completion after the dot (`.`) character.
{% endhint %}
## Lookup Ship Info from Customer
Let's explore a bit more the idea of handling UI events in code. This time we will lookup the order's shipping info from the related customer record.
### Add Ship Info Fields
First, let's get some of the ship info fields on the form.
1. Click the Place Fields button to show the **Place Fields Wizard**. (You used this wizard when you first created the form)
2. Choose the following fields: `shipaddress`, `shipcity` and `shipcountry`.
3. You can adjust their `cssPosition` property to align next to the other fields:\
`left=calc( 25% + 200px)`
### Add a Data Change Handler
The ship info will be empty when a new record is created, but we can add some logic to lookup from the related customer record whenever the `customerid` changes.
1. Select the Customer field and double-click its `onDataChange` event to open the Method Selection Wizard.
2. Create a new method in the form named `onDataChangeCustomer`
3. Create Private and click OK
The new method stub is created in the same file as the `newRecord` method.
### Add the Lookup Logic
In the new method, enter the following code to lookup the address info from the related customer and enter it as shipping info.
```javascript
function onDataChangeCustomer(oldValue, newValue, event) {
// Lookup ship info from customer address
shipaddress = orders_to_customers.address;
shipcity = orders_to_customers.city;
shipregion = orders_to_customers.region;
shippostalcode = orders_to_customers.postalcode;
shipcountry = orders_to_customers.country;
return true;
}
```
That's it! Just a few lines to copy the data over. Save all your editors and preview the changes in the NG Client.
Preview of the ship info lookup in the NG Client
You can see that a blank, new record is created and when the user selects the customer for the order, the ship info is immediately looked-up from the related table.
## Create Related Records
Now that we can create order records, the user will want to add Order Detail records as well. Let's add a button and a method to create the related records.
1. From the pallet, drag a button on to your form. Set the `text` to "Add Item"
2. Double-click the `onAction` event and create a new method in the form called `addItem`.
3. Set the `cssPosition` property to have the button anchor right: 240,**10**,-1,-1,115,30
4. Create private. Click OK and Show.
The `addItem` method stub is created in the `orders.js` file and ready for your logic. Enter the following code to your method.
```javascript
function addItem(event) {
// create the record
orders_to_order_details.newRecord();
// set the quantity default to 1
orders_to_order_details.quantity = 1;
}
```
Here you can see that the relation, `orders_to_order_details`, can be used in code to reference the related JSFoundSet object and the `newRecord` method is available. You can also reference the data providers of the related foundset, such as `quantity`. Save your editors and try it out in the NG Client.
{% hint style="success" %}
**Related Foundsets**\
You just created a record through a related foundset. The Servoy platform understands your relation and will insert the record with the correct foreign key automatically!
{% endhint %}
## Lookup Product Price
Let's add a little more logic to our form, again using UI event handlers. This time, let's lookup the price of a product and auto-fill the Unit Price column for an Order Detail.
### Create a Relation to Products
To be able to lookup the price of the product, we must first create a relation to the `products` table. You've done a few of these by now, so it should just take a moment
Relation Editor: order_details_to_produtcs
1. Create a new relation object. Select `example_data.order_details` as the *from* data source. Select `example_data.products` as the *destination*.
2. Match the `productid` column from both tables. Save your editor and continue.
### Create a Handler for Data Change Event
Next, we will implement a handler for the data change event, so that we can update the price based on the selected product.
1. Select the Order Details grid and in the Component Properties Editor, double-click the `onColumnDataChange` event to open the Method Selection Wizard.
2. Create the new method in the form and click OK
3. Once again the method stub is added to your `orders.js` file
Enter the following code into your method stub:
```javascript
function onColumnDataChange(foundsetindex, columnindex, oldvalue, newvalue, event, record) {
// Check if the first column (Product) was changed
if(columnindex == 0){
orders_to_order_details.unitprice =
orders_to_order_details.order_details_to_products.unitprice;
}
return true;
}j
```
This data change event is a little different than the one for the Type Ahead used previously for the Custom field. This event is called when *any* of the grid's columns (or rows) have a data change. Fortunately, more information is passed in as arguments to help us figure it out.
**Evaluate which column changed**\
The `columnindex` parameter can be used to infer which column has changed. The Product column is the first column in the grid and therefore index `0`.
**Lookup Product Price**\
Once again, using the relations you have made, you can assign a value to the `unitprice` column in the `order_details` table from the `unitprice` column in the `products` table.
{% hint style="success" %}
**Relation Chaining**\
Notice how you can chain relations together to easily traverse your data model in code. The Servoy platform will handle all the querying and updating without a hitch.
{% endhint %}
## Create an Order Total Calculation
In the final step in this chapter, we will create another, more complex, calculation to derive the total value of an order.
### Using the Servoy Resource Locator
Open your orders table in the Table Editor. This time we'll learn to use the [**Servoy Resource Locator**](/reference/servoy-developer/object-editors/servoy-resource-locator) to quickly find and open the table.
The Servoy Resource Locator
1. From the main toolbar, click the  button `(alt+shift+k)` to open the Servoy Resource Locator.
2. Type the first few characters of the file you are searching for, i.e. "orders"
3. Use the mouse or down arrow key to choose the resource to open and click OK or type ENTER.
### Create the Calculation Script
Create a new calculation, just as you did in the previous chapter. The name should be `order_total` and the data type should be `NUMBER`.
Using Code Completion CTRL-SPACE
{% hint style="info" %}
**Code Completion is Great!**\
Notice in this image that code completion can be used to generate a template of a **for loop** and other constructs. After which you can TAB through each element of the template.
{% endhint %}
```javascript
function order_total()
{
var sum = 0;
for (var i = 1; i <= orders_to_order_details.getSize(); i++) {
var record = orders_to_order_details.getRecord(i);
sum += record.subtotal;
}
return sum;
}
```
In this code, we iterate over the Order Details and tally the subtotal of each line.
1. Create a local variable for the sum
2. Create a for loop (use code completion - `CTRL-SPACE`) to iterate over records in the related `orders_to_order_details` foundset.
3. Access each `order_detail` record and add its `subtotal` calculation to the sum using the `+=` operator.
4. Every calculation must return a value, in this case the `sum` variable.
### Place a Data Label - Order Total
We are finally ready to place the `order_total` calculation on the form. Let's use a new component, **Data Label** to show the total. This component is a regular label, but binds directly to a data provider and allows us to apply a format.
1. From the pallet, drag the Data Label component onto your form
2. Double-click the dataProvider property in the Component Properties Editor and select the `order_total` calculation.
3. Edit the `format` property and apply a format to a localized currency.
4. You may edit the `cssPosition` property to align it next to your Add Item button: `270,130,-1,-1,80,30`
5. Edit the styleClass property and add a style of `font-weight-bold`
6. You may add another label next to it with the text "Order Total"
Save your editors and preview your work in the NG Client.
Fully editable records and dynamic calculations
{% hint style="success" %}
**Chapter Complete**. Nice work! Now you should be able to:
* Create a new order record
* Lookup and attach a customer, which does an auto-fill of the ship info.
* Next you should be able to add order detail records.
* As you lookup the product, you should get an auto-fill of the unit price.
* Finally, you should see your calculations for subtotal and order total automatically refreshing as you make edits.
{% endhint %}
# Chapter 5
Working with extensions
## Overview
In this chapter we will install a few extensions to enhance our application. The Servoy platform is highly extensible and it's easy add capabilities to your project.
## Key Concepts Covered
* **Servoy Extensions**
* **Servoy Package Manager** (SPM)
* **Modules**
* **Form Variables**
* **Search Module Extension**
* **Scopes**
* **Chart Component Extension**
## Add Search Capability
In this section, we will install a special extension to enable text-based searching of our database. Then we will bind it to a **TextBox** component and process user input to find records in our example database.
### Install a Search Module
Let's install the **SvySearch** module using the **Servoy Package Manger (SPM)**.
Install SvySearch module via the SPM
1. At the top of your pallet, click "Get more components". This opens the SPM.
2. Click "Modules" and scroll down to locate "SvySearch" Click the `+` button to install it.
{% hint style="info" %}
**The Servoy Package Manager**
Also known as the **SPM**, it makes it easy to manage the **extensions** in your project.
{% endhint %}
The SvySearch module will be installed in your workspace and will be referenced as one of your solution's modules. You will find it located under the **Modules** mode in the **Solution Explorer**.
{% hint style="info" %}
**Modules**
Servoy is modular by design. Any Solution can be reused as a "Module" and it's easy to include modules in your application via the SPM. However, you can also create your own modules to simplify larger applications, reuse code and standardize development.
{% endhint %}
### Create a Form Variable
Because we will search based on user input, we will use a **Form Variable** to capture and reference the input.
Create Form Variable
1. From the Solution Explorer, expand your `orders` form and locate the `variables` node.
2. Right-click and select "Create Variable" to open the **Form Variable Editor**.
3. Give your variable a name `searchText`, the Type as `TEXT` and the default `null` value.
4. This also opens the `orders.js`, showing your variable declaration in source.
{% code fullWidth="false" %}
```javascript
/**
* @type {String}
*
* @properties={typeid:35,uuid:"02248C57-9D99-427A-99FB-748B405F2022"}
*/
var searchText = null;
```
{% endcode %}
{% hint style="info" %}
**Form Variables** work like any other Data Provider, such as database columns, except that they are not stored to a database. They hold session state, such as user input. You can also **manually type** the variable declaration into your form.js file.
{% endhint %}
### Add a Search Field
Let's add a field to the form and bind it to our form variable to capture the user input.
1. From the pallet, drag the **TextBox** component to the form, placing it above your orders grid.\
(You can use the `cssPosition` property `10,75%,-1,10,140,30`)
2. Double-click the `dataProvider` property to open the **Data Provider Chooser**. Select the `searchText` form variable that you just created.
3. Edit the `placeholderText` property to be "Enter Search Criteria" This text will be displayed when the field is empty.
### Handle Input Event
To run the search, we'll need to bind an event handler to call the search module that we added. This time, we'll use the **onAction** event, which we've seen for buttons. However, for an input field, this will be triggered when the user hits the `ENTER` key.
1. Double-click the `onAction` event of the TextBox component that you just added. This opens the **Method Selection Wizard**.
2. Choose "Create method in Form". Name your method `onSearch` and select "Create Private". Click "OK and Show" to finish. The new method stub is opened in the `orders.js` file.
3. Let's add a few lines to the method. Don't be shy, you will get help from code completion based on the installed module.
{% code lineNumbers="true" %}
```javascript
function onSearch(event) {
var search = scopes.svySearch.createSimpleSearch(foundset);
search.setSearchAllColumns();
search.setSearchText(searchText);
search.loadRecords(foundset);
}
```
{% endcode %}
* Line `2` we access the **SvySearch** module and create a new search object based on this form's **DataSource** or **FoundSet**.
* Line`3` we indicate that the search will look across all `TEXT` columns in the data source.
* Line 4 we indicate that the search object should use the user input, captured in our form variable `searchText`.
* Line `5` we bring it home by applying the search object to this form's **FoundSet**. This will run the search and load records in our form.
{% hint style="info" %}
**Scopes**
You'll notice a new keyword `scopes` in this example. So far, we've only looked at form-level script files. Scopes are another kind of script file used to reference top-level packages of code in your solution and other modules. Enter `"scopes."` to get code completion on all available scopes.
{% endhint %}
Save your editors and preview the change in the NG Client. Enter some text in your search input field and hit `ENTER`.
Search by Country
Here you can see that the search module is able to match on all orders where the `shipcountry` column = Germany. Try it out! What happens when you enter a string fragment, such as "germ" or part of a city name instead?
### Search on Related Data
This is nice, but let's try something a little more...."advanced". Suppose we wanted to search on a customer name or a product in and order? Fortunately the **SvySearch** module is quite powerful and this can be done by adding just a little code.
function onSearch(event) {
var search = scopes.svySearch.createSimpleSearch(foundset);
search.setSearchAllColumns();
search.setSearchText(searchText);
search.addSearchProvider('orders_to_customers.companyname');
search.addSearchProvider('orders_to_order_details.order_details_to_products.productname');
search.loadRecords(foundset);
}
Let's examine the two lines of code added to enable a related search.
* Line `5` we add the related data provider for the company name
* Line `6` we add the order detail records and the related product name.
Save your editor and preview the results in the NG Client.
Enter "big" and you will match on the orders of the customer "The Big Cheese". Enter "coffee Germany" and you will match on all orders shipped to Germany having coffee as one of the products.
{% hint style="success" %}
**Robust Searching**\
Well done. You added a robust user text search to your application in just a few lines of code. The Servoy platform handles all the parsing of terms, caching and querying. This approach works equally well on very large databases.
{% endhint %}
## Add a Chart Component
Let's finish the chapter by adding a simple chart to our orders form to help visualize the breakdown of the products. It takes just a few clicks and demonstrates how to add extend your pallet of components.
### Install the ChartJS Component
In the previous example, we added a **module**, which included some code libraries we took advantage of. In this example, we'll add a new **component** package.
Chart Component
1. Open the **Servoy Package Manager** (SPM) as you did in the previous example. In the list of components, scroll to find the **ChartJS** package and click the `+` button to install.
2. After the package installs, the component is available drag a chart component from the pallet onto your form.
3. You may position the component right of your input fields, by setting the `cssProperty` to `86,-1,-1,calc(25% + 390px),200,170`
4. Next, we'll set the data binding for the component. Double-click the `foundset` property to open the **Foundset Chooser**. Select your `orders_to_order_details` relation and click `OK`.
5. Expand the `dataproviders` sub-property and double-click the `label` property to open the Data Provider Chooser. Select `order_details_to_products.productname.` This will be the display value for the chart.
6. Do the same for the `value` sub-property and choose the `subtotal` calculation that you made in a previous chapter.
7. Just for fun, let's switch the chart type. Edit the `type` property and select `DOUGHNUT`.
Save your editors and preview the changes in the NG Client.
Chart Component Preview
You can see that the chart labels match the product name and the values match the subtotal. When the selected order record changes, the chart is redrawn. Moreover, when the input values to the subtotal calculation change (i.e. unit price), the chart is redrawn.
{% hint style="success" %}
**Data-Bound Components**\
Nice work! In only a few clicks (and zero lines of code) you have a working chart. Most UI Components in Servoy are data-bound by default, meaning they *always* reflect the real-time values in the connected data source....automatically.
{% endhint %}
# Get Help
This guide will explain how to get support when building with Servoy
## Community Forum
Whether you are just getting started or have become a Servoy expert, the [Servoy Forum](https://forum.servoy.com/) is perhaps the fastest way to get help from the vibrant Servoy developer community. Your questions will be answered by people who have walked in your shoes.
## Just Ask the Docs!
Did you know that Servoy's documentation site comes with AI-powered search? We've trained a large-language-model on our docs and it is ready to answer your question. You can try it out...right now! Just click `Ctrl-K` |`Cmd-K`.
The search dialog has two options: `Search` provides a traditional key-word search and `Lens` gives a prompt to ask an open question. The response includes an AI-generated natural language answer, plus suggested follow-up questions and most important, links to the pages where the content can be found.
Example AI prompt and response in Lens mode
## Appsurance Program
Servoy provides a best-in-class expert services program for onboarding, training and project steering to help ensure the success of critical software projects. We call it "Appsurance" (Application+Assurance). Our experts live it everyday and we know how to help. Please contact your account representative or for more info.
## Support Level Agreement
# SuLA Instructions
Instructions on how to receive commercial support.
### Overview
As an open-source platform, Servoy allows anybody to file bugs and feature requests in our case management system. However, we offer preferred Support Levels to paying customers with guaranteed response metrics. This page covers the instructions for receiving commercial support.
{% hint style="info" %}
If you are uncertain if you have a SuLA, contact your designated account manager or .
{% endhint %}
### Accessing the Incident Portal
You can access the [**Incident Portal**](https://servoy-cloud.atlassian.net/servicedesk/customer/portal/7) directly and log in if you have an account. You can also link to it from our general case management system at [**support.servoy.com**](https://support.servoy.com)**.**
{% hint style="info" %}
Case Management System vs Incident Portal. **What's the difference?!**\
Because Servoy is an open source platform, we publish our bugs and features transparently on our case management system [**support.servoy.com**](https://support.servoy.com)**.** The [**Incident Portal**](https://servoy-cloud.atlassian.net/servicedesk/customer/portal/7) is for private support for SuLA customers.
{% endhint %}
#### Creating a Support Account
On both the [**Incident Portal**](https://servoy-cloud.atlassian.net/servicedesk/customer/portal/7) and the case management system, You will be prompted to log in. If have not already created an account, you can do so using your **email**.
{% hint style="info" %}
**Which email address to use ?**
In order for your account to be linked to the proper SuLA, you must use your **company email** that is associated with the organization which holds the SuLA.
For example, use **** instead of ****
{% endhint %}
Once you have provided your email, you will be sent a password reset link. Check your spam/promotion folders to ensure you have received the email.
Enter a secure password to finish creating your account. Your user profile will be associated to the SuLA company by domain name.
Use your company email to register for a support account
### Creating a Request
Once you have logged in, you are ready to create a support request.
Select an issue type and enter the required info
1. The first step is to select the **type of issue** that you are experiencing. The available issue types include:
* **Bug** - Select this issue type if you believe that you are experiencing a bug with the Servoy Platform or developer environment that is impacting your organization.
* **Feature Request** - Select this issue type if you believe that the Servoy Platform is missing an essential feature which will help your organization
* **Technical Question** - Select this issue type if you are experiencing an issue in development and deployment, but you don't believe (or you are uncertain) that it is caused by a Servoy Bug.
* **General Question** - Select this issue if you have a non-technical or general question about the Servoy Platform, such as billing or company policies or procedures.
2. Next, provide a **summary** and **description** of your issue. Be sure to be specific and provide all relavent information. The more information we have up front, the faster our agents can help to resolve your issue.\
\
Please include any supporting **attachments**, such as log files or screenshots of errors or warnings, etc. (Dont worry, your issue's details will be **private** to just you, and your organization if you choose to share it with colleagues).\
\
Finally, don't forget to enter the **Servoy Version**(s) on the developer or deployment environment(s) where you are experiencing the issue. This will help us to narrow down the caue more quickly.
### Confirmation
After you have submitted your support request, you will receive **confirmation via email** with links to monitor your issue in the [**Incident Portal**](https://servoy-cloud.atlassian.net/servicedesk/customer/portal/7).
Email confirmation of support request
You will continue to receive notifications via email for any activity on this support issue. You may also **reply directly** in the email to message the support team.
# SuLA Terms
Servoy Support-Level Agreements (SuLA)
### Overview
As an open-source platform, Servoy allows anybody to file bugs and feature requests in our case management system. However, we offer preferred Support Levels to paying customers with guaranteed response metrics. This page covers the terms of Servoy's commercial support.
{% hint style="info" %}
If you are uncertain if you have a SuLA, contact your designated account manager or .
{% endhint %}
### 1. Support Levels/Types
Customers having a commercial license contract with Servoy will have indicated in their Product Order Form (POF) the agreed Support Level. In this document the details per level are indicated:
| Support Level | Coordinator | Response Time \* | Blocker Items \*\* |
| ------------- | ----------- | ---------------- | ------------------ |
| A | No | Best Effort | 5 days |
| B | No | 40 Hours | 8 Hours |
| C | Yes | 8 Hours | 4 Hours |
| D | Yes | 4 Hours | 2 Hours |
\* Response time during the SuLA support windows; see below par 6.\
\*\* Most critical Bugs (Blocker) must be reported to a live person of Servoy by phone.
### 2. Technical Support General Process
Servoy utilizes a 3-step support model for problem & feature resolution:\
● Qualification\
● Resolution design\
● Start of the Resolution
\
When initial contact with Servoy is made, a team member of Servoy will validate all information details relevant to the question or issue. Once all relevant information is available, the case is considered qualified. Part of this is separating issues into Bugs, feature requests, technical questions and other questions. Required information for a case to be qualified is described in Addendum 5 as attached hereto. A unique case number will be assigned and delivered to the contact person by Servoy, either verbally, via web request or via e-mail. This case number will be used to track any given issue from initial contact to final problem resolution. All cases can be monitored in the support system at on our [**Incident Portal**](https://servoy-cloud.atlassian.net/servicedesk/customer/portal/7)
\
Once a case is qualified, the resolution for it is designed and if applicable presented to Partner/End-User. After resolution approval by Partner/End-User, the designed resolution will be planned and implemented. The response time between a question/case and the provision of a qualification is called: T1. The time between a qualified question and resolution design is called: T2. The time between an approved resolution design and start of resolution is called: T3.
### 3. Contacting Support
All cases must be entered into the case system of Servoy which can be found on our [**Incident Portal**](https://servoy-cloud.atlassian.net/servicedesk/customer/portal/7).
If Partner/End-User is entitled to phone support, the numbers are:
* **USA Dial: + 1 866 489 5147** (support level agreement)
* **NL Dial: +31 (0)20 229 3641**
### 4. Communications
Extreme severity situations (Blocker) may require the parties to use the telephone for immediate communications. The parties will follow up such communications using: [**https://support.servoy.com**](https://support.servoy.com). For tracking and recording purposes, each party is responsible for funding the cost of this communication at their own location. In circumstances where materials have to be exchanged using facsimile, courier services, or other delivery services, each party is responsible for funding the cost of these exchanges at their own location.
### 5. Non-Servoy Bugs / Errors
If during the normal Support processes and appropriate management review, Servoy believes that a problem reported by Partner/End-User may not be due to a Bug, Servoy will notify Partner/End-User accordingly. In such event Partner/End-User may instruct Servoy:
1. to proceed with problem determination at its possible expense as set forth herein; or
2. that Partner/End-User does not wish the problem to be further pursued at its expense.
If Partner/End-User requested Servoy to continue with the problem determination at its expense and Servoy determines that the problem was not caused by a Bug, Partner/End-User shall pay Servoy at the Servoy's then-current standard hourly consulting rate at a time and material basis for all work performed in connection with such determination (including the discovery time spent), plus reasonable related expenses incurred therewith. Partner/End-User shall not be liable for the payment of the Servoy's then-current standard consulting rates in the event:
1. Problem determination or repair to the extent problems has been caused by a Bug; or
2. Work performed after Partner/End-User has notified Servoy in writing that it no longer wishes problem determination to be continued at its possible expense (such notice shall be deemed given when actually received by Servoy). If Partner/End-User instructs Servoy that it does not wish the problem pursued at its possible expense or such determination requires effort in excess of Partner/End-User's instructions, Servoy may, at its sole discretion, investigate the issue without any liability.
### 6. Support Windows
There are 2 types of Support windows:
* 5 (working days) \* 12: Extended business hours 7AM-7PM
* 5 (working days) \* 8: Normal business hours 9AM-5PM
The support window/working days are depending on the SuLA type as agreed upon the Product Order Form as well as the timezone of the Servoy branch providing the Support.
* USA time zone is PST
* NL time zone is CET
### 7. Designated Contacts
Servoy requires that designated contacts be identified with person-specific e-mail addresses.
* It is important to know and authenticate with whom Servoy is working; person-specific e-mail addresses assist in identifying valid contacts.
* The Partner/End-User can always "cc" their Support alias (if they have one and if they so choose) and Servoy will "reply all" in the Support request response, alleviating concerns the Partner/End-User has on situations where the contact who originally initiated the request for Support is "out of the office" but the organization has other support experts on hand working the issue.
* All Partner/End-User personnel contacting Servoy for Support must be familiar with the latest Major\
Release of the Software and the current issue as to which Partner/End-User requires assistance.
* Partner/End-User agrees that contact with Servoy will be through a limited number of contacts
### 8. Coordination (Levels C and D)
For the SuLA level (C\&D), Servoy will dedicate a coordinator to assist in facilitating escalation. The coordinator is a non-technical representative, whose goal is to build close relationships and promote an understanding of infrastructure and processes. Some work items (especially those associated with critical situations) may need to be expedited. In such event, Partner/End-User will notify Servoy of the critical situation (Blocker) and Servoy will agree to work with Partner/End-User on providing the appropriate solution for each critical situation. If appropriate, Partner/End-User can also contact the support coordinator of Servoy
### 9. Program Upgrades
Servoy permits upgrades of Support at any time during the Term at the beginning of each calendar month. Servoy shall not issue prorated refunds. Notwithstanding the aforementioned, in the event Servoy modifies this SuLA and such modification has or will have substantial impact on the contents of the Support, Partner/End-User may terminate the Support forthwith upon Servoy implementing any such modification.
### 10. Offince Locations
Servoy USA
Servoy NL
30721 Russell Ranch Rd Suite 140, Westlake Village, CA 91362 Tel +1 866 489 514
Servoy Web Site: [**https://www.servoy.com**](https://www.servoy.com)
# Develop
This guide will cover all the aspects of how to develop applications
# Application Design
# Forms
This guide will introduce the fundamental concept of Forms
## Overview
Forms are the fundamental unit of UI space in a Servoy application. Each form represents an area of screen on which interactions with UI Components, data and scripted logic takes place.
## Placing Components
### Layout Manager
Layout managers control how components are arranged and behave in forms. Each form uses one of the following layout managers and a solution may mix forms having any of these types.
* [**Simple Layout**](/guides/develop/application-design/forms/layout-management/css-position) **(CSS Position)**
* [**Advanced Layout**](/guides/develop/application-design/forms/layout-management/home) **(Responsive)**
* [**Abstract**](/guides/develop/application-design/forms/layout-management/abstract-form) **(No UI)**
## Data Binding
A Servoy Form is typically bound to a single database table and the form will always contain a single foundset which is bound to the same table. Much of the action in the user interface, such as a user editing data fields, directly affects the form's foundset. Conversely, actions taken on the foundset, such as programmatically editing data, is immediately reflected in the form.
Often, there can be several different forms which are bound to the same table. In most cases the forms will share the same foundset and thus provide a unified view. For example, imagine a form showing a list of customer records, where clicking on one of the records switches to another form showing a detailed view of only the selected record. The forms will automatically stay in sync and there is no need to coerce the forms to show the same record. Exceptions to this behavior include scenarios where forms are shown through different relations, or have been explicitly marked to use a separate foundset.
## Properties
Each form has a set of [properties](/reference/servoycore/object-model/solution/form#property-summary) that can be easily set and customized at design time using the form editor in Servoy developer, but also at runtime.
## Events
The form's behavior can be handled using the specific [events](/reference/servoycore/object-model/solution/form#events-summary) list, which can be found in each form's properties tab.
## Nesting Forms
Servoy developer allows users to nest forms, meaning a form can contain one or more other forms. This practice is helpful when a form needs to be used in more than one place, in order to avoid time consuming, repetitive work and also when it comes to changes, they would be done in one place only and applied everywhere the form is used. Nesting forms is done by using [form containers](/reference/servoyextensions/ui-components/form-containers#form-containers).
## Scripting Forms
A developer can create or add form and form elements related business logic to the application using the form scope, by accessing the [script editor](/reference/servoy-developer/object-editors/scripting-editor).
## Form Inheritance
A way of reusing objects is by [form inheritance](/guides/develop/application-design/forms/form-inheritance#form-inheritance). Servoy allows you to extend forms by other forms, which is a mechanism of creating new Forms (Child Form) that extend existing Forms (Super or Parent Form). As forms contain UI as well as variables and methods, all of this can be inherited and thus reused.
## Form Security
Servoy allows users to quickly set up user groups and enable multilevel security access to solutions. Form level security settings can be specified at the group level for an entire form or for selected form elements via the [Form Editor Security](/guides/develop/application-design/forms) subtab.
# Layout Management
## Overview
Layout managers control how components are arranged and behave in forms. Each form uses one of the following layout managers and a solution may mix forms having any of these types.
* [**Simple Layout** ](/guides/develop/application-design/forms/layout-management/css-position)**(CSS Position)**
* [**Advanced Layout**](/guides/develop/application-design/forms/layout-management/home) **(Responsive)**
* [**Abstract**](/guides/develop/application-design/forms/layout-management/abstract-form) **(No UI)**
# Simple Layout
This section of the guide covers the Simple (CSS Position) layout manager
## Overview
When creating a form, one must always select a layout type. **Simple** (CSS Position) is the easiest and most common way to arrange components on a form. It is the recommended approach for most projects.
## Quick Start
When creating a form, leave the default option for Simple (CSS Position) layout on the [New Form Wizard](/reference/servoy-developer/object-editors/new-form-wizard). Drag components onto the form, or set the [**cssPosition**](/reference/servoycore/dev-api/application/cssposition) property. See [examples](#examples) below.
## How it works
**Simple** or CSS Position layout is the default layout type for building forms. It controls the location and dimensions of the components on the form and the dynamic behavior of the components as the form size changes.
{% hint style="info" %}
Just to clarify, one does not need to know *anything* about CSS technology to use this layout type. The mechanism for laying out components is straightforward and can be learned in a few minutes.
{% endhint %}
### Form (min)sizes in the browser
A form has in its properties 4 values that are used to set or not set the minimum sizes (min-width and min-height) of the form when showing in a container (like tabpanel).
First the form has "minWidth" and "minHeight" properties that should be set, those are also the design size what you see in the Form Editor in the developer.
Those 2 properties are set at runtime also on the form based on the other 2 properties: useMinHeight and useMinWidth, those 2 properties can have 3 states: true,false and not\_set When it is true the min-width/height is set in the browser that could result in a tabpanel showing scrollbars because it tries to fit the form for that minimum size. If it is false then the min-xxx are not set, and the form size is as big as the viewport (the visible area). If the form has some components outside this viewport, the form will overflow and scrollbars will appear. The scrolling area will be exactly as big so it can fit exactly all the components.
The difference between true and false is that the size of the form is bigger when true because it has also marging to the right and bottom when you have designed marging there around the button that is placed in the bottom right corner. But also if you have button that is right, bottom alligned, see CSS Postion below, then the button is alligned to the min size of the form instead of the viewport that you see, but the button will still move down or to the right if it has more space.
|If the value is not\_set then it will fallback to a default, the standard default value is 'true', but this can be overwritten by setting a client property for 1 of both sizes:
```
application.putClientProperty(UICONSTANTS.DEFAULT_FORM_USE_MIN_HEIGHT,false);
```
### CSS Position
When using CSS Position, you will specify the [cssPosition](/reference/servoycore/dev-api/application/cssposition) property of every component that you place on the form. The position property contains six values to control location and behavior. They are expressed as a single string having the form: `top, right, bottom, left, min-width, min-height`. Each value can be expressed as an absolute [pixel](#pixel-values) value or a relative [percentage](#percentage-values) value. The property can also be set a [calculated](#calculated-values) (pixel & percentage) value.
Property
Description
Top
The top edge of the component, expressed as a distance from the top of the form.
Right
The right edge of the component, expressed as a distance from the right of the form.
Bottom
The bottom edge of the component, expressed as a distance from the bottom of the form.
Left
The left edge of the component, expressed as a distance from the left of the form.
Min-Width
The width of the component
Min-Height
The height of the component
#### Pixel Values
You can use pixel values to dictate the *exact* location or dimension. This means that the value will not change, regardless of the form's changing size.
```json
// Example 10 pixels from top of form
top: 10
```
#### Percentage values
You can use percentage values to specify the *relative* location or dimension. This means that the value will change, depending on the form's changing size.
```
// example 10% of the form's height from top of form
top: 10%
```
#### Calculated Values
You can combine percentages and pixel values to specify a calculated location or dimension. This is ideal for adding absolute gaps between relatively positioned components.
```
// example 50% of the form's height from top, plus additional 10 pixels
top: calc(50% + 10px)
```
#### Ignored Values
You can also choose to ignore a property. To do this, enter a value of `-1` to skip the property. Doing so will allow another property to have precedence. For example, suppose that you wanted to have a component placed 10 pixels from the left edge and always occupy 25% width of the form. In this case, you may choose to ignore one of the `right` location property.
```
// 10 px from left, 25% width
left: 10
right: -1
width: 25%
```
{% hint style="info" %}
**Conflicts**: Sometimes position values can be in conflict. In this case there is an order of precedence. **Location** values will always override their corresponding **dimension** values. For example, a component having both values for `left` and `right` will take precedence and the `width` value will be ignored (except to enforce the minimum)
{% endhint %}
### Dragging Components
When editing a Simple layout form, you can also drag to move and resize components inside the [Form Editor](/reference/servoy-developer/object-editors/form-editor). This will update the **cssPosition** property.
## Examples
Below are a few examples of simple layout arrangements. Try them out on your own components.
**Fully-Anchored, ignore dimensions**\
In this example, This component will always be 10 pixels from each edge of the form. It will grow and shrink with a changing form size, but it will never move. (width and height are ignored)
```
cssPosition: 10,10,10,10,-1,-1
```
**Anchored top-left, fixed dimensions**\
In this example, the component will maintain a fixed position on its top-left corner and it will maintain a fixed size. It will not grow, shrink or move.
```
cssPosition: 10,-1,-1,10,400,200
```
**Anchored top, bottom & left, relative width**\
In this example, the component is anchored to the left and it will grow and shrink vertically. It will also grow and shrink horizontally, relative to the width of the form. (height is ignored)
```
cssPosition: 10,-1,10,10,50%,-1
```
**Anchored top, bottom & left, calculated right**\
This example shows two components which occupy two columns and leave a 10px gap. Their respective `right` and `left` values use a calculated value (50% of the form width, plus an extra 10px). This is ideal to create a gap between components
```
cssPosition: 10,calc(50% + 10px),10,10,-1,-1
cssPosition: 10,10,10,calc(50% + 10px),-1,-1
```
# Fully Responsive
## Fully Responsive
## Overview
When creating a form, one must always select a layout type. **Advanced** (Responsive) is the most complex layout manager, but allows developer the greatest flexibility to dictate how components and containers respond to different form sizes.
## How it works
**Advanced** (Responsive) is the most complex layout manager, differently from the [Simple CSS](/guides/develop/application-design/forms/layout-management/css-position), you don't define the exact location and the size in pixels with simple drag and drop; instead you will create a layout stucture with Layout Containers nesting components into them. Location and dimension of the components, as well how it responds to changes of the Browser size, is determined by the structure you create with Layout Containers, the custom style you may apply and for certain components by the actual content of the components; for instance a label containing a long text can overflow to the next line instead of having the text cutted.
{% hint style="info" %}
**Advanced (Responsive) vs** [**Simple CSS**](/guides/develop/application-design/forms/layout-management/css-position) In most cases it is recommended to use [Simple CSS](/guides/develop/application-design/forms/layout-management/css-position), but Advanced (Responsive) is purposed for specific situations:
* for applications that need to show/hide components at different scales
* for applications where the layout should respond to the internal content, etc.
{% endhint %}
## [Bootstrap 12-Grid Layout](/guides/develop/application-design/forms/layout-management/home/b12grid#bootstrap-12-grid-layout)
* [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container)
* [Row](/guides/develop/application-design/forms/layout-management/home/b12grid#row)
* [Column](/guides/develop/application-design/forms/layout-management/home/b12grid#column)
## [Bootstrap 12-Grid Layout Templates](/guides/develop/application-design/forms/layout-management/home/b12grid#bootstrap-12-grid-layout-templates)
* [Row-With-Column](/guides/develop/application-design/forms/layout-management/home/b12grid#row-with-column)
* [Label-And-Field](/guides/develop/application-design/forms/layout-management/home/b12grid#label-and-field)
* [Responsive-Form-Template](/guides/develop/application-design/forms/layout-management/home/b12grid#responsive-form-template)
## [Flexbox](/guides/develop/application-design/forms/layout-management/home/flexbox#flexbox)
* [Flex-Container](/guides/develop/application-design/forms/layout-management/home/flexbox#flex-container)
* [Flex-Item](/guides/develop/application-design/forms/layout-management/home/flexbox#flex-item)
* [Flexbox Layout](/guides/develop/application-design/forms/layout-management/home/flexbox#flexbox-layout)
## Other Layout Containers
On addition to the Bootstrap Grid system there are several Layout Containers which can be combined to build a complex responsive form:
* [Custom Div](/guides/develop/application-design/forms/layout-management/home/custom-div#custom-div)
* [Collapsible Container](/guides/develop/application-design/forms/layout-management/home/collapsible-container#collapsible-container)
* [Simple Collapsible](/guides/develop/application-design/forms/layout-management/home/simple-collapsible#simple-collapsible)
* [Center Container](/guides/develop/application-design/forms/layout-management/home/center-container#center-container)
* [Inline Group Container](/guides/develop/application-design/forms/layout-management/home/inline-group-container#inline-group-container)
## Mixing Simple CSS and responsive forms
Here is the webinar section that covers mixing Simple CSS and Responsive forms:
{% embed url="" %}
Webinar
{% endembed %}
### CSS Position Container
The CSS Position Container is a special container which can be used to create as a [Simple CSS](/guides/develop/application-design/forms/layout-management/css-position) a block of the Advanced (Responsive) Form offering a great flexibility for the design of your form.
To edit the content of the CSS Position Container is requested to use [Form Editor](/reference/servoy-developer/object-editors/form-editor) Zoom mode which strips out from the editor any outer layout container and allows you to work only with the Zoomed section; as soon you drop a CSS Position Container into the Form you are requested to Zoom in for editing; you can Zoom out any moment using the Zoom Out icon and come back to edit the content of the CSS Position Container using the Zoom In icon.
You can place any component into the CSS Position Container as if is a [Simple CSS Form](/guides/develop/application-design/forms/layout-management/css-position), therefore using same rules; the location of the elements in it will be relative to the CSS Position Container block.
Set the size property **width** and **height** to control the height and the minimum width of the CSS Position container.
**Constraints** : can be edited only when Zoom in [Form Editor](/reference/servoy-developer/object-editors/form-editor), the contained elements cannot be moved into a different container.
Webinar section for CSS Position Container:
{% embed url="" %}
Webinar
{% endembed %}
#### Create a CSS Position Container
Create a CSS Position Container
These are the steps for creating a CSS Position Container:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **CSS Position Container** in *Templates* subsection of the *Bootstrap 12-Grid* section in the components' pallet
3. Drag and drop the **CSS Position Container** component inside any other container components, **except** [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Row](/guides/develop/application-design/forms/layout-management/home/b12grid#row)
4. Click on the "Yes" button of the pop-up that appears after adding the **CSS Position Container**, in order to get into Zoom mode and be able to edit the content of the component
5. While in Zoom mode you can add and edit other needed components available for [Simple CSS](/guides/develop/application-design/forms/layout-management/css-position) forms
## Nesting responsive forms
In responsive layouts, when you nest multiple forms using tab panels or other types of container-components it may happen that a tab/child form that has in it directly "*row*" layout containers (so no root layout "*container*" or layout "*container-fluid*") shows unwanted scroll-bars. That happens because bootstrap requires that all '*row*' divs must either be put in a '*container*', a '*container-fluid*' or in a '*column*', while in the case of a tabpanel for example the parent DOM Element is just some intermediate div. Because '*row*' has negative margins of -15px and parent intermediate div might not have padding of 15px, the scrollbars can appear (if that div has overflow: auto). For example:
```javascript
container
row
column
div style="overflow: auto" // the intermediate div of container-component
row // results in a scrollbar because of margin -15px
columns
```
The problem does not appear when a '*row*' is inside a '*column*', a '*container*' or a '*container fluid*' - because those have a padding of 15px defined. However, bootstrap doesn't allow nesting of containers in it's layout docs - so adding a container layout as root of child/contained form is not an option. But as the tabpanel might want to contain absolute forms as well (for example), that intermediate div cannot always set a 15px padding - as that might not be necessary... So we just need to change the margins of such rows as in the rule below (that is included already in "*standard\_ngclient.css*"):
```css
div:not(.container):not(.container-fluid):not([class^="col-xs-"]):not([class^="col-sm-"]):not([class^="col-md-"]):not([class^="col-lg-"])
> .row {
margin-right: 0;
margin-left: 0;
}
```
# Bootstrap 12-Grid
## Bootstrap 12-Grid Layout
### Overview
This is the bootstrap 12 grid layout package for making [**responsive forms**](/guides/develop/application-design/forms/layout-management/abstract-form). It is meant to work with the bootstrap components package or any other compatible component packages. You can build a responsive layout for your form using this combination or components and layouts. 12grid is based on bootstrap grid system, see for more details.
See below the Layout Containers which can be found within the Bootstrap 12-Grid Layout package:
### Container
Container, based on the Bootstrap [Container](https://getbootstrap.com/docs/5.0/layout/containers) is used to contain, pad, and (sometimes) center the content within them. While containers can be nested, most layouts do not require a nested container.
**Constraints** : A Container can be dropped only at the root of the form layout and can contain **only** [Row](#row), therefore you will be allowed to drag & drop into it **only** [Row](#row) layout or templates starting with rows (e.g. Row and 1 Column, Label and Field...).
#### Create a Container
Create a Container
These are the steps for creating a Container:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your [**responsive form**](/guides/develop/application-design/forms/layout-management/abstract-form)
2. Find **Container** in *Bootstrap 12-Grid* section of the components' pallet
3. Drag and drop the **Container** component in the form
4. Add at least one [Row](#row) component
### Row
Rows are wrappers for columns. Each column has horizontal padding (called a gutter) for controlling the space between them. This padding is then counteracted on the rows with negative margins to ensure the content in your columns is visually aligned down the left side. Rows also support modifier classes to uniformly apply column sizing and gutter classes to change the spacing of your content.
**Constraints** : A row can contain **only** [Column](#column) containers.
#### Create a Row
Create a Row
These are the steps for creating a Row:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your [**responsive form**](/guides/develop/application-design/forms/layout-management/abstract-form)
2. Find **Row** in *Bootstrap 12-Grid* section of the components' pallet
3. Drag and drop the **Row** component in:
* empty space of the form, as an independent component
* inside a [Container](#container) component
* inside a [Column](#column) component
4. Add at least one [Column](#column) component
### Column
Columns are at the core of the 12 Grid Layout system. Nested within [Row](#row) containers, they can divide the parent row's width to up 12 blocks of same relative size, allowing you to create different combinations of elements that span any number of columns. Column classes indicate the number of template columns to span (e.g., col-4 spans four). widths are set in percentages so you always have the same relative sizing.
**Constraints** : A column can contain any component and any layout containers **except** for [Container](#container), [Column](#column) or [Flex Item](/guides/develop/application-design/forms/layout-management/home/flexbox#flex-item).
Can nest rows into a column to further organize the layout:
#### Create a Column
Create a Column
These are the steps for creating a Column:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Column** in *Bootstrap 12-Grid* section of the components' pallet
3. Drag and drop the **Column** component in a [Row](#row) component
4. Add other needed components inside the **Column**, **except** for [Container](#container), [Column](#column) or [Flex Item](/guides/develop/application-design/forms/layout-management/home/flexbox#flex-item)
***
## Bootstrap 12-Grid Layout Templates
The following are ready to use layout templates based on the 12 Grid Layout.
### Row-With-Column
A quick start for a 12 Grid layout. These 3 templates *Row with 1 Column*, *Row with 2 Columns*, *Row with 3 Columns* are row layout containing already 1, 2 or 3 equally sized columns.
#### Create a Row-With-Column
Create a Row-With-Column
These are the steps for creating a Row-With-Column:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Row with 1 Column** / **Row with 2 Columns** / **Row with 3 Columns** in the *Bootstrap 12-Grid* section of the components' pallet
3. Drag and drop the component in:
* empty space of the form, as an independent component
* inside a [Container](#container) component
* inside a [Column](#column) component
4. Add other needed components inside the **Column**, **except** for [Container](#container), [Column](#column) or [Flex Item](/guides/develop/application-design/forms/layout-management/home/flexbox#flex-item), even other columns inside the row, if needed
### Label-And-Field
A predefined template which comes with a row and 2 columns ( md-4 and md-8 ) having a [Label](/guides/develop/application-design/ui-components/buttons-and-text/label) component in the first column and a [Textbox](/guides/develop/application-design/ui-components/input-controls/textbox) component in the second column.
#### Create a Label-And-Field
Create a Label-And-Field
These are the steps for creating a Label-And-Field:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Label-And-Field** in *Templates* subsection of the *Bootstrap 12-Grid* section in the components' pallet
3. Drag and drop the **Label-And-Field** component in:
* empty space of the form, as an independent component
* inside a [Container](#container) component
* inside a [Column](#column) component
4. Edit the [Label](/guides/develop/application-design/ui-components/buttons-and-text/label) component in the first column and the [Textbox](/guides/develop/application-design/ui-components/input-controls/textbox) component in the second column, or even add other components if needed
### Responsive-Form-Template
A predefined layout of nested rows and columns; you can further edit it by adding or removing other layout containers.
#### Create a Responsive-Form-Template
Create a Responsive-Form-Template
These are the steps for creating a Responsive-Form-Template:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Responsive-Form-Template** in *Templates* subsection of the *Bootstrap 12-Grid* section in the components' pallet
3. Drag and drop the **Responsive-Form-Template** component into an empty space of the form, as an independent component
4. Edit the [Columns](#column) and [Rows](#row); you can also add or remove components inside
# Flexbox
## Overview
The Flexbox layout containers are using the CSS3 [Flexbox layout](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox) model; Flexbox is a one-dimensional layout method for arranging items in either rows or columns.\
The Flexbox layout involves a container ([Flex Container](#flex-container)) and one or more children ([Flex Item](#flex-item)). There are several properties which can be set in either the parent [Flex Container](#flex-container) or the [Flex Item](#flex-item) children using the [Servoy properties](https://github.com/Servoy/gitbook/blob/master/guides/develop/application-design/forms/layout-management/fully-responsive/broken-reference/README.md) view in the IDE.
## Flex-Container
It is the parent container of the [Flexbox layout](#flexbox-layout). It comes already with 3 [Flex Item](#flex-item) children; you can further add or remove any [Flex Item](#flex-item).
You can modify the layout using it's 3 unique properties:
* **data-direction**: determines if the flex items in it should be arranged as rows or columns.
* **data-align-items**: determines how the flex items are laid along the flex container.
* **data-justify-content**: determines how the available space should be distributed among the flex items.
**Constraints** : Can contain only [Flex Item](#flex-item).
Below an example of flex container with data-justify-content set to space-around.
### Create a Flex-Container
Create a Flex Container
These are the steps for creating a Flex Container:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Flex Container** in *Flex CSS* subsection of the *Bootstrap 12-Grid* section in the components' pallet
3. Drag and drop the **Flex Container** component in:
* empty space of the form, as an independent component
* inside any other container components, **except** [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Row](/guides/develop/application-design/forms/layout-management/home/b12grid#row)
4. Edit the existing [Flex Items](#flex-item); you can further add or remove any [Flex Item](#flex-item)
## Flex-Item
Flex items can be dropped into [flex containers](#flex-container). As the flex containers, each flex item has its own set of unique properties used to determine how the item is layout within its container.
* **data-align-items**: determines how the flex items are laid along the flex container.
* **data-grow**: determines the ability of the item to grow, relatively to other flex items, when there is more space available.
* **data-shrink**: determines the ability of the item to shrink, relatively to other flex items, when necessary.
In the example below the first item from the left doesn't grow since has `flex-grow=0`. The middle item has `flex-grow=1`, the last item has the `flex-grow=2` therefore grows twice as much of the middle flex item.
### Create a Flex-Item
Create a Flex Item
These are the steps for creating a Flex Item:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Flex Item** in *Flex CSS* subsection of the *Bootstrap 12-Grid* section in the components' pallet
3. Drag and drop the **Flex Item** component in:
* empty space of the form, as an independent component
* inside a [Flex Container](#flex-container)
4. Edit the **Flex Item** and add other needed components inside
## Flexbox Layout
## Overview
The flexbox layout divides the available height in 3 vertical sections, **header**, **content** and **footer**. The **header** and the **footer** section will grow in height depending on their content while the **content** section will take all the remaining height and show a scrollbar if the content doesn't fit.
{% hint style="info" %}
**IMPORTANT!** The Flexbox layout is using the CSS3 Flexbox layout model. Now days the Flexbox model is largely supported from modern browsers (see [supported browsers](https://caniuse.com/#feat=flexbox)). However there are few known issues with IE and Safari (open the [Known issues](https://caniuse.com/#feat=flexbox) tab).
{% endhint %}
## Getting Started
You can drop Servoy any Servoy Web Components and nest other 12Grid containers into the **header**, **footer** and **content** section.
You may decide to leave empty the **header** or **footer** section, not necessarily you need to use these section; however you may use at least one of these 2 sections; otherwise you may not use this container at all since there is no benefit on using only the **content** section.
{% hint style="info" %}
**IMPORTANT!** The parent container of the flexbox layout MUST have a known height, the flexbox layout is not useful at all if the height of it's top container is 'auto' (which is an unknown value). In case the parent container of the flexbox layout is the Servoy form itself, add a CSS styleClass to the form which will let the form use 100% of the available height.
{% endhint %}
{% hint style="info" %}
**IMPORTANT!** if the form is nested within another form via a tab/tabless panel, the panel MUST have a known height as well, so that the inner form can use 100% of the panel height.
{% endhint %}
## Create a Flex Layout
Create a Flex Layout
These are the steps for creating a Flex Layout:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Flex Layout** in *Templates* subsection of the *Bootstrap 12-Grid* section in the components' pallet
3. Drag and drop the **Flex Layout** component in:
* empty space of the form, as an independent component
* inside any other container components, **except** [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Row](/guides/develop/application-design/forms/layout-management/home/b12grid#row)
4. Edit the **header**, **footer** and **content** sections of the **Flex Layout** and add other needed components inside
### Flexbox Layout and Table Components
When a Servoy Table Component from the [Bootstrap components](https://github.com/Servoy/bootstrapcomponents) package or from the [Servoy Extra Components](/guides/develop/application-design/data-modeling/databases/tables) package or from the Servoy NG Grids package is placed within the content section of the flexbox layout as direct child, the table height will use 100% of the available height if the `responsiveHeight` property is set to `0`.
**NOTE** for the [Table](/guides/develop/application-design/data-modeling/databases/tables) component from the Servoy Extra package the property `responsiveDynamicHeight`, should be set to `false` if you wish to use all the available height of the content section; if the `responsiveDynamicHeight` is set to `true` the [Table](/guides/develop/application-design/data-modeling/databases/tables) will have a max-height equal to the design `responsiveHeight` property of the Table; the max-height may be smaller than the available height resulting in unused space.
If instead you prefer to use the design height of the [Table](/guides/develop/application-design/data-modeling/databases/tables) component, wrap the [Table](/guides/develop/application-design/data-modeling/databases/tables) component within a different 12Grid container. However letting the table use a different height than the available height in the content section may result in bad UX for the User since may result in double vertical scrollbars.
### Nesting Flexbox Layout
You can nest multiple FlexLayout within the **content** section to sub-divide the available height of the content section.
In the sample above the available height of the first flexbox layout content is divided in 2 blocks of 50% height using the custom styleClass `half-size`.
```css
.half-size {
height: 50%;
}
```
### Flexbox Layout and tab/tablesspanel
If you include a [tab panel](/guides/develop/application-design/forms/form-containers/tab-panel) or tabless panel into the **content** section and you would like to let the panel use all the available height of the content section add a CSS styleClass to the [tab panel](/guides/develop/application-design/forms/form-containers/tab-panel) or tabless panel component to let the panel use 100% of the height.
# Custom Div
## Overview
A simple div, is the simplest Layout Container; can be used to divide the space in multiple blocks without additional rules.
## Getting Started
### Create a Custom Div
Create a Custom Div
These are the steps for creating a Custom Div:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Custom Div** in *Templates* subsection of the *Bootstrap 12-Grid* section in the components' pallet
3. Drag and drop the **Custom Div** component in:
* empty space of the form, as an independent component
* inside any other container components, **except** [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Row](/guides/develop/application-design/forms/layout-management/home/b12grid#row)
4. Add other needed components inside the **Custom Div**, **except** for [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Column](/guides/develop/application-design/forms/layout-management/home/b12grid#column) or [Flex Item](/guides/develop/application-design/forms/layout-management/home/flexbox#flex-item)
# Collapsible Container
## Overview
The **Collapsible Container** is a responsive container, to be used in a **Servoy Responsive Form**, which behaves as a toggle on small screen sizes. When the size of the screen is smaller than 992px it presents a toggle section on which the user can click to toggle the visibility of its content. On medium and large screens instead it always displays its content and hides its toggle section.
**Note**: layout containers are not stateful, therefore the Collapsible Container will always return to its design state when the user navigates away from the form or the browser is refreshed.
## Getting Started
You can drop Servoy Web Components and nest other 12Grid containers into both toggle and container sections.
The Collapsible Container uses attributes of its inner *div* containers to achieve the collapsible behavior. To obtain the collapsible behavior the `data-target` attribute of the `collapsible-toggle` must target the correspondent `collapsible-container` via CSS selector.
It is recommended to edit the default value and set an unique `id` attribute in the `collapsible-container`; adjust accordingly the `data-target` of the `collapsible-toggle`.
## Create a Collapsible Container
Create a Collapsible Container
These are the steps for creating a Collapsible Container:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Collapsible Container** in *Templates* subsection of the *Bootstrap 12-Grid* section in the components' pallet
3. Drag and drop the **Collapsible Container** component in:
* empty space of the form, as an independent component
* inside any other container components, **except** [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Row](/guides/develop/application-design/forms/layout-management/home/b12grid#row)
4. Add other needed components inside the **Collapsible Container**, **except** for [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Column](/guides/develop/application-design/forms/layout-management/home/b12grid#column) or [Flex Item](/guides/develop/application-design/forms/layout-management/home/flexbox#flex-item)
## Change default toggle to expanded
The collapsible container is collapsed by default on small screens; you can modify the classes of its sections to change the default state to be expanded.
Add the class `show` for Titanium Client / `in` for NGCLient to the div having the `collapsible-container` class property to expand the content by default and remove the class `collapsed` from the div having `collapsible-toggle` class property.
## Customize the toggle icon.
You can decide to remove the icon in the toggle section and place any component of your choice to be used as icon.
# Simple Collapsible
## Overview
The **Simple Collapsible container** allows to toggle the visibility of its content in a **Servoy Responsive Form**. It has a toggle section and a content section; the toggle section is always visible and toggles the visibility of the content section when the user clicks on it.
**Note**: layout containers are not stateful, therefore the Simple Collapsible will always return to its design state when the user navigates away from the form or the browser is refreshed.
## Getting Started
You can drop Servoy Web Components and nest other 12Grid containers into both toggle and content section.
The Simple Collapsible uses attributes of its inner `div` containers to achieve the collapsible behavior. To obtain the collapsible behavior the `data-target` attribute of the `simple-collapsible-toggle` must target the correspondent `simple-collapsible-content` via CSS selector.
It is recommended to edit the default value and set an unique `id` attribute in the `simple-collapsible-content`; adjust accordingly the `data-target` of the `simple-collapsible-toggle`.
## Create a Simple Collapsible
Create a Simple Collapsible
These are the steps for creating a Simple Collapsible:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Simple Collapsible** in *Templates* subsection of the *Bootstrap 12-Grid* section in the components' pallet
3. Drag and drop the **Simple Collapsible** component in:
* empty space of the form, as an independent component
* inside any other container components, **except** [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Row](/guides/develop/application-design/forms/layout-management/home/b12grid#row)
4. Add other needed components inside the **Simple Collapsible**, **except** for [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Column](/guides/develop/application-design/forms/layout-management/home/b12grid#column) or [Flex Item](/guides/develop/application-design/forms/layout-management/home/flexbox#flex-item)
## Change default toggle to collapsed
The collapsible container is expanded by default; you can modify the classes of its sections to change the default state to collapsed.
Remove the classes `in` and `show` from the `simple-collapsible-content` class property to collapse the content by default and add the class `collapsed` in the `simple-collapsible-toggle` class property.
## Customize the toggle icon.
You can decide to remove the icon in the toggle section and place any component of your choice to be used as icon.
You can also change the default icon in the styleSheet of your solution using CSS3.
```css
.simple-collapsible-toggle > .simple-collapsible-icon {
font-family: "Glyphicons Halflings";
display: inline-block;
}
.simple-collapsible-toggle > .simple-collapsible-icon:before {
content: "\e113"; /* GlyphIcon chevron down when expanded */
}
.simple-collapsible-toggle.collapsed > .simple-collapsible-icon:before {
content: "\e114"; /* GlyphIcon chevron up when collapsed */
}
```
# Center Container
## Overview
The **Center Container** allows its content vertically and horizontally in a **Servoy Responsive Form**.
You can drop Servoy Web Components and nest other 12Grid containers into its content section. You can also nest center container within each other.
To center the content vertically the parent container must have a known height; if the height of it's parent container is not known the container will center it's content only horizontally.
Note that 12Grid rows and columns usually don't have a known height (unless their height is set in the styleSheet), therefore the center container contained in a 12Grid column will center its content vertically.
## Getting Started
## Create a Center Container
Create a Center Container
These are the steps for creating a Center Container :
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Center Container** in *Templates* subsection of the *Bootstrap 12-Grid* section in the components' pallet
3. Drag and drop the **Center Container** component in:
* empty space of the form, as an independent component
* inside any other container components, **except** [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Row](/guides/develop/application-design/forms/layout-management/home/b12grid#row)
4. Add other needed components inside the **Center Container**, **except** for [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Column](/guides/develop/application-design/forms/layout-management/home/b12grid#column) or [Flex Item](/guides/develop/application-design/forms/layout-management/home/flexbox#flex-item)
## Center multiple elements
You can drop Servoy Web Components and nest other 12Grid containers into its content section to center multiple elements as a single block. You can also nest multiple center containers to center sub-content within the content section; note that as for the 12Grid rows, sub-content of the center container are centered only horizontally by default (unless you define a known height or min-height to the sub center container via CSS); this is the case since the content of the top-level center container doesn't have a known height but it is 'auto' calculated depending on its content.
## Width and Height of the center content
The center content section doesn't have a known height and width but its height and width are set to '*auto*'; this means that the content section will grow as much it needs (depending on its content) and not more.
Since the content section height and width are *auto*, a container or a web component which has width or height equal to 100%, will also fallback into width and height equal to *auto*. For example a textbox component having a *form-control* class, which usually takes 100% of the width, won't grow to the whole available width instead will use its default width (which has different value depending on browser version and OS system).
### Min Width
You can set a min-width to the content section (using CSS classes) to stretch its content to a minimum dimension; inner containers and components having width equal to 100% will grow up to at least the min-width of the content section.
# Inline Group Container
## Overview
The **Inline Group Container** allow syou to use at best the available width dividing the available width in 3 horizontal section, **left**, **right** and **content**; the left and the right section will use all and only the necessary width depending on their content (if any); the **content** section instead will use all the remaining width.
## Getting Started
You can drop Servoy any Servoy Web Components and nest other 12Grid containers into the **left**, **right** and **content** section.
You may decide to leave empty the **right** or **left** section, not necessarily you need to use these section; however you may use at least one of these 2 sections; otherwise you may not use this container at all since there is no benefit on using only the **content** section.
{% hint style="info" %}
**IMPORTANT!** The parent container of the inline group container MUST have a known width, the inline group container is not useful at all if the width of its top container is `auto` (which is an unknown value).
{% endhint %}
## Create an Inline Group Container
Create an Inline Group Container
These are the steps for creating an Inline Group Container :
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of your **responsive form**
2. Find **Inline Group Container** in *Templates* subsection of the *Bootstrap 12-Grid* section in the components' pallet
3. Drag and drop the **Inline Group Container** component in:
* empty space of the form, as an independent component
* inside any other container components, **except** [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Row](/guides/develop/application-design/forms/layout-management/home/b12grid#row)
4. Add other needed components inside the **left**, **right** and **content** sections of **Inline Group Container**, **except** for [Container](/guides/develop/application-design/forms/layout-management/home/b12grid#container), [Column](/guides/develop/application-design/forms/layout-management/home/b12grid#column) or [Flex Item](/guides/develop/application-design/forms/layout-management/home/flexbox#flex-item)
## Fixed Left/Right Section Size
You may force the **left** and or **right** section to a fixed width by setting the respectively the `data-leftsize` and `data-rightsize` attribute of the inline group container to one of the pre-defined values `xs`, `sm`, `md`, `lg`.
Setting a fixed size to a section is particularly useful when you want to align multiple label and fields using multiple inline group containers.
You can override the default sizes of the pre-defined values by adding the following CSS rules to the CSS styleSheet of your Solution.
```css
/* Inline Group Sizes */
.inline-group[data-leftsize="xs"] > .inline-group-left,
.inline-group[data-rightsize="xs"] > .inline-group-right {
width: 40px;
}
.inline-group[data-leftsize="sm"] > .inline-group-left,
.inline-group[data-rightsize="sm"] > .inline-group-right {
width: 80px;
}
.inline-group[data-leftsize="md"] > .inline-group-left,
.inline-group[data-rightsize="md"] > .inline-group-right {
width: 120px;
}
.inline-group[data-leftsize="lg"] > .inline-group-left,
.inline-group[data-rightsize="lg"] > .inline-group-right {
width: 160px;
}
```
You can of course decide also to add your own CSS class to set a specific width to the section instead of using the pre-defined sizes.
## Responsive Section
You can enable a responsive behavior for the **left** section using the attribute `data-responsive` of the inline-group-container. You can select a breakpoint value (`sm`, `md`, `lg`) for which the left section will move into a new line when the screen size is smaller than the breakpoint value; see the [Bootstrap CSS Media Query](https://getbootstrap.com/docs/3.0/css/#grid-media-queries) for the breakpoint values.
## Nesting Inline Group Containers
You can nest multiple inline group container within the content section to sub-divide the available width of the content section.
# Abstract Form
## Overview
When creating a form, one must always select a layout type. An **Abstract** (No UI) layout can be used to create a base form, from which other forms can inherit. The benefit of having a base form be Abstract, is to allow child forms to implement any UI, while still inheriting the properties and event bindings, as well as logic from the Abstract parent.
## Quick Start
When creating a form, select the form type option **Abstract** (No UI) in the [New Form Wizard](/reference/servoy-developer/object-editors/new-form-wizard). Then you may set form properties and event handlers, as well as implement logic to be inherited as you please.
{% hint style="info" %}
For more information on creating an Abstract Base Form see the guide on [**Form Inheritance**](/guides/develop/application-design/forms/form-inheritance).
{% endhint %}
# Form Containers
## Overview
Form Containers allow you to insert one or more form(s) into a form. This is a common practice when a form needs to be displayed in several places, it also facilitates using relations between the main and contained form when related data needs to be shown.\
Containers can be added to a form using the Place Elements Wizards toolbar, the Palette, or the Solution Explorer.
## Types of Form Containers:
[Form](/reference/servoycore/object-model/solution/form#form) containers:
* [Form Container](/guides/develop/application-design/forms/form-containers/form-container#form-container)
* [Tab Panel](/guides/develop/application-design/forms/form-containers/tab-panel#tab-panel)
* [Split Pane](/guides/develop/application-design/forms/form-containers/split-pane#split-pane)
* [Collapse](/guides/develop/application-design/forms/form-containers/collapse#collapse)
* [Accordion Panel](/guides/develop/application-design/forms/form-containers/accordion-panel#accordion-panel)
[Form Component](/reference/servoycore/object-model/solution/form-component#extendsform) containers:
* [Form Component Container](/guides/develop/application-design/forms/form-containers/form-component#form-component)
* [List Form Component Container](/guides/develop/application-design/forms/form-containers/list-form-component#list-form-component)
# Form Container
## Overview
The "Form container" component is a container that shows 1 form inside it. It has no additional UI decorations.\
The contained form can optionally show related data.
It is suited for use in both Advanced (Responsive) and Simple CSS forms.
## Get Started
### Creating a Form Container
Create a Form Container
Here are the steps for creating a Form Container:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of the form where you need to place a **Form Container**
2. Find **Form Container** in *Form Containers* section in the components' pallet
3. Drag and drop the **Form Container** component in the desired place of the form
4. Select the [`containedForm`](/reference/servoyextensions/ui-components/form-containers/form-container#containedform) property, where you set the name of the form you want to be displayed in the container
5. Optionally, you can [use a relation](#using-a-relation) by selecting the [`relationName`](/reference/servoyextensions/ui-components/form-containers/form-container#relationname) property, where you set the [relation](/guides/develop/application-design/data-modeling/relations) between the main form and the contained form
6. Edit other [**Form Container** properties](/reference/servoyextensions/ui-components/form-containers/form-container#properties) if needed
{% hint style="info" %}
It is recommended to set a specific `name` in the **Form Container** properties in order to make it easier to use it later in scripting.\
Example: `"fc_order_details"`.
{% endhint %}
### Using a relation
The contained form can show related data. In order to do this, you need to have the following:
1. Set the [`datasource`](/reference/servoycore/object-model/solution/form#datasource) property on the main form
2. Set the [`datasource`](/reference/servoycore/object-model/solution/form#datasource) property on the contained form
3. Make sure that the [relation](/guides/develop/application-design/data-modeling/relations) from datasource table of the main form to datasource table of the contained form exists, otherwise it needs to be created
4. Set the above relation in the [`relationName`](/reference/servoyextensions/ui-components/form-containers/form-container#relationname) property of the Form Container
Once everything is set, the contained form will show related data according to the selected record in the main form. When the selected record changes in the main form, so will the related data from the contained form.
## Scripting a Form Container
[**Form Container** properties](/reference/servoyextensions/ui-components/form-containers/form-container#properties) can be also set in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor).
### Setting the Contained Form
Here is an example of how to programmatically set the contained form, including relationName, in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor) of the main form:
```javascript
/**
* Callback method when form is (re)loaded.
*
* @param {JSEvent} event the event that triggered the action
*
* @properties={typeid:24,uuid:"5C166B77-060A-4E85-AD9F-EB20B194E55F"}
*/
function onLoad(event) {
// TODO Auto-generated method stub
// fc_order_details = the name of the form container in the main form
// order_details = the contained form
// orders_to_order_details = relation between datasource table of the main form to datasource table of the contained form
elements.fc_order_details.containedForm = forms.order_details;
elements.fc_order_details.relationName = orders_to_order_details;
}
```
Other [**Form Container** properties](/reference/servoyextensions/ui-components/form-containers/form-container#properties) can be set the same way, by using `elements.FormContainerName.FormContainerPropertyName`.
# Tab Panel
## Overview
The TabPanel component is a tabbed container that can hold one or more forms. But only one of them is visible at a time.\
The active/visible form can be changed using the tab buttons or from code. At runtime, tabs can be added from code, and can be removed either from code or from the UI. Tabs can optionally show related data.
It can be used in both responsive and anchored layouts.
## Get Started
Tab Panel
### Creating a Tab Panel
Create a Tab Panel
Here are the steps for creating a Tab Panel:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor) of the form where you need to place an **Accordion Panel**
2. Find **TabPanel** in *Form Containers* section in the components' pallet
3. Drag and drop the **TabPanel** component in the desired place of the form
4. Set the tabs; this can be done via [wizard](/guides/develop/application-design/forms/form-containers/accordion-panel#setting-the-tabs-property-via-the-wizard) or in the [properties panel](#setting-the-tabs-property-in-the-properties-panel)
5. Edit other [**TabPanel** properties](/reference/servoyextensions/ui-components/form-containers/tabpanel#properties) if needed
{% hint style="info" %}
It is recommended to set a specific `name` in the **Tab Panel** properties in order to make it easier to use it later in scripting.\
Example: `"tabpanel_orders"`.
{% endhint %}
{% hint style="info" %}
It is recommended to set a specific `name` in the **Tab Panel tab** properties in order to make it easier to use them later in scripting.\
Example: `"tab_customers"`.
{% endhint %}
### Setting the tabs property via the wizard
Property configurator for tabs wizard
After dragging the container in the form, the `Property configurator for tabs` wizard appears. In order to set the tabs using the wizard, you need to do the following steps:
1. Find in the left side of the wizard the contained form you need: it can have a related or unrelated datasource
2. Click on the form name
3. The selected form will appear on the right side of the wizard, showing some of the tab properties:
1. `CONTAINEDFORM` : the form shown in the tab
2. `RELATIONNAME` : the name of the relation between datasources of main and contained forms; this field will be empty if the relation doesn't exist
3. `TEXT`: the tab's title text ([i18n](/reference/servoy-developer/solution-explorer/resources/i18n#i18n) and custom HTML supported)
4. `delete` icon : you can remove a tab by clicking the icon
4. Click `OK` button after all tabs have been added
### Setting the tabs property in the properties panel
Adding and editing tab properties
After dragging the container in the form, the `Property configurator for tabs` wizard appears. Close the editor without setting anything here, find the **Accordion Panel** in the form editor, click it and proceed with the following steps:
1. Add a tab. There are 2 ways of adding a tab:
1. Select the [`tabs`](/reference/servoyextensions/ui-components/form-containers/tabpanel#tabs) property and click the `+` button in order to add a tab. Next tabs can be added the same way or by clicking the `+` button (`insert a new array item below`) of another tab. You can change the tabs' order by dragging them into the desired placed inside the **TabPanel** (in the form editor).
2. Drag and drop `tab` component (of an **TabPanel** in *Form Containers* section in the components' pallet) into the **TabPanel** container (in the form editor)
2. Expand the [`tabs`](/reference/servoyextensions/ui-components/form-containers/tabpanel#tabs) property to see the list of tabs. They are also shown in the **TabPanel** container (in the form editor)
3. In order to edit each tab, expand it or click the tab name in the **TabPanel** container (in the form editor) and set the properties:
1. [`containedForm`](/reference/servoyextensions/ui-components/form-containers/tabpanel#containedform): the form shown in the tab
2. [`disabled`](/reference/servoyextensions/ui-components/form-containers/tabpanel#disabled): whether that tab is enabled or not
3. [`hideCloseIcon`](/reference/servoyextensions/ui-components/form-containers/tabpanel#hidecloseicon): whether a close icon is shown or not (only applicable when [`showTabCloseIcon`](/reference/servoyextensions/ui-components/form-containers/tabpanel#showtabcloseicon) is set to `true`)
4. [`iconStyleClass`](/reference/servoyextensions/ui-components/form-containers/tabpanel#closeiconstyleclass): style class for the tab's icon
5. [`imageMedia`](/reference/servoyextensions/ui-components/form-containers/tabpanel#imagemediaid): image to be drawn in tab header
6. [`name`](/reference/servoyextensions/ui-components/form-containers/tabpanel#name): a name for this tab
7. [`relationName`](/reference/servoyextensions/ui-components/form-containers/tabpanel#relationname): optional relation for the form to be shown
8. [`text`](/reference/servoyextensions/ui-components/form-containers/tabpanel#text): the tab's title text ([i18n](/reference/servoy-developer/solution-explorer/resources/i18n#i18n) and custom HTML supported)
9. [`toolTipText`](/reference/servoyextensions/ui-components/form-containers/tabpanel#tooltiptext): the text message when a user hovers their cursor ([i18n](/reference/servoy-developer/solution-explorer/resources/i18n#i18n) and custom HTML supported)
### Using a relation
The contained form of the tabs can show related data. In order to do this, you need to have the following:
1. Set the [`datasource`](/reference/servoycore/object-model/solution/form#datasource) property on the main form
2. Set the [`datasource`](/reference/servoycore/object-model/solution/form#datasource) property on the contained form
3. Make sure that the [relation](/guides/develop/application-design/data-modeling/relations) from datasource table of the main form to datasource table of the contained form exists, otherwise it needs to be created
4. Set the above relation in the [`relationName`](/reference/servoyextensions/ui-components/form-containers/tabpanel#relationname) property of the corresponding tab
Once everything is set, the contained form will show related data according to the selected record in the main form. When the selected record changes in the main form, so will the related data from the contained form.
## Customizing the Tabs
### Setting the tab text
Tab's title [text](/reference/servoyextensions/ui-components/form-containers/tabpanel#text) property can be set by entering a value in the property field or by entering the [Text Property Editor](/reference/servoy-developer/object-editors/text-property-editor). Usually this will be plain text or it can contain data from table columns, aggregations, calculations, relations or from and scopes variables, all of them can be combined, as well. [i18n](/reference/servoy-developer/solution-explorer/resources/i18n#i18n) is also supported.
Examples:
Tab text - plain text
Tab text - including database column
Tab text - including form variable
Tab text - i18n
### Setting the tooltip text
Tab's [tooltip text](/reference/servoyextensions/ui-components/form-containers/tabpanel#tooltiptext) property can be set by entering a value in the property field or by entering the [Text Property Editor](/reference/servoy-developer/object-editors/text-property-editor). Most often, this will just be plain text that describes what will happen on-click. It can also contain data from table columns, aggregations, calculations, relations or from and scopes variables - all of them can be combined. [i18n](/reference/servoy-developer/solution-explorer/resources/i18n#i18n) is also supported.
### Closable Tabs
TabPanel component can also have closable tabs, when needed.
#### Enabling/Disabling Tab Close
In order to enable the option to have closable tabs, the user must check [showTabCloseIcon](/reference/servoyextensions/ui-components/form-containers/tabpanel#showtabcloseicon) property of the TabPanel component. This applies to all tabs, so in case when not all tabs should be closable, the user can check [hideCloseIcon](/reference/servoyextensions/ui-components/form-containers/tabpanel#hidecloseicon) property of the **tab**; this will remove the close icon of the tab.
#### Setting the close Icon
The close icon can be set by editing the [closeIconStyleClass](/reference/servoyextensions/ui-components/form-containers/tabpanel#closeiconstyleclass) property of the TabPanel.
### Custom Tab Markup
Tab's title [text](/reference/servoyextensions/ui-components/form-containers/tabpanel#text) property supports custom HMTL content.
Example:
Tab text - custom HMTL
{% hint style="warning" %}
In order for the custom HTML content to be correctly displayed we need to make sure that it will not be sanitized by using `.putClientProperty(UICONSTANTS.TRUST_DATA_AS_HTML,true)`
```javascript
function onShow(firstShow, event) {
// TODO Auto-generated method stub
elements.tabpanel_orders.putClientProperty(UICONSTANTS.TRUST_DATA_AS_HTML,true);
}
```
**Only enable this setting if the data shown can always be trusted and is never composed of data from an external system or user.**
{% endhint %}
## Scripting a Tabpanel
[**TabPanel** properties](/reference/servoyextensions/ui-components/form-containers/tabpanel#properties) can be also set in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor).\
You can find a list of AccordionPanel API methods [here](/reference/servoyextensions/ui-components/form-containers/tabpanel#api).
### Changing Selected Tab
Here is an example of how to programmatically set the active tab in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor) of the main form:
```javascript
/**
* TODO generated, please specify type and doc for the params
* @param index {Number}
*
* @properties={typeid:24,uuid:"78CE78AF-AC5A-458B-A611-84DDC07878B3"}
*/
function setActiveTab(index){
elements.tabpanel_orders.selectTabAt(index)
} // call this function after the TabPanel container is fully loaded on the page and set the desired index value
```
### Adding a Tab
Here is an example of how to programmatically add a tab in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor) of the main form:
```javascript
function onShow(firstShow, event) {
// TODO Auto-generated method stub
elements.tabpanel_orders.addTab(forms.suppliers,'Suppliers'); // Adds a tab to this accordion with that form and text
}
```
### Removing a Tab
Here is an example of how to programmatically remove a tab in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor) of the main form:
```javascript
function onShow(firstShow, event) {
// TODO Auto-generated method stub
var x = elements.tabpanel_orders.tabs.length;
elements.tabpanel_orders.removeTabAt(x-1); //Removes a tab of the given index. Returns true if this was sucessfull.
}
```
### Handling Tab Change Event
Here is an example of how to use the [`onChange` event](/reference/servoyextensions/ui-components/form-containers/tabpanel#onchangemethodid) of an TabPanel in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor) of the main form:
Saving the active tab index in the `onChange` event(fired after a different tab is selected) of the TabPanel container:
```javascript
/**
* Fired after a different tab is selected.
*
* @param {Number} previousIndex The previous tab index
* @param {JSEvent} event
*
* @private
*
* @properties={typeid:24,uuid:"0A044286-CB21-4CCC-A8AA-284137F1D22E"}
*/
function onChange(previousIndex, event) {
// TODO Auto-generated method stub
application.setUserProperty(controller.getName()+"."+elements.tabpanel_orders+".activeTab",elements.tabpanel_orders.activeTabIndex.toString())
}
```
Checking if there is a saved previous active tab index and set it in the `onShow` main form event:
```javascript
/**
* @type {String}
*
* @properties={typeid:35,uuid:"2FD6AD36-9779-49D2-B4A7-985C7C73B66C",variableType:8}
*/
var activeTab;
/**
* Callback method for when form is shown.
*
* @param {Boolean} firstShow form is shown first time after load
* @param {JSEvent} event the event that triggered the action
*
* @private
*
* @properties={typeid:24,uuid:"37E091B7-6FD0-47E8-94E4-A22585A3C717"}
*/
function onShow(firstShow, event) {
// TODO Auto-generated method stub
activeTab = application.getUserProperty(ontroller.getName()+"."+elements.tabpanel_orders+".activeTab");
if (activeTab)
{
elements.tabpanel_orders.selectTabAt(parseInt(activeTab));
}
}
```
#### Blocking a tab change
Here is an example of how to block a tab change using the [`onTabClicked` event](/reference/servoyextensions/ui-components/form-containers/tabpanel#ontabclickedmethodid) of an TabPanel in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor) of the main form:
```javascript
/**
* Fired when the user clicks on a tab. When false is returned, the tab switch is prevented.
*
* @param {JSEvent} event The event that triggered the action
* @param {Number} clickedTabIndex The index of the tab that was clicked
* @param {String} dataTarget The value of the closest data-target attribute when found
*
* @return {Boolean}
*
* @private
*
* @properties={typeid:24,uuid:"0C9D0DEA-5D52-4E2E-B5D9-2E510FC2BE9F"}
*/
function onTabClicked(event, clickedTabIndex, dataTarget) {
var editedRecords = databaseManager.getEditedRecords();
if (editedRecords.length>0) {
var button = plugins.dialogs.showInfoDialog('Pending changes', 'Some fields have changes. How would you like to proceed?', 'Stay on tab', 'Leave')
if (button == 'Leave') {
return true;
}
} else {
return true;
}
return false;
}
```
### Handling a Tab Close Event
Here is an example of how to use the [`onTabClose` event](/reference/servoyextensions/ui-components/form-containers/tabpanel#ontabclosemethodid) of an TabPanel in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor) of the main form:
```javascript
/**
* @type {Array
