# Chapter 1 ## 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`. ![](/files/JEYzjGJ3aVD5ctMUuK4U) 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`. ![](/files/taGzjzv8CjET0fKM5ZHR) ### 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. ![](/files/WbvmUYmFWwjG2RdbU0Ad) 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. ![](/files/W1mFDv7ewBmyU4KjAEW0) 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` ![](/files/dy9RYsK7iTZAitvjI41p) The Form Editor should open and you should see a form having the fields that you selected. ![](/files/4Sb0UtsTA3LfiVRjbyXy) ## 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 ![](/files/b6871TRIQVWn9JxfwbNm)icon. ![](/files/wKN3PHl718SMCItWLbZm) 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. ![](/files/nT7Zbcr2mi8oGDsFyjPn) ### 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.md#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 ![](/files/KsAAh32UF1aZ8azJvEG1)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.md). 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. ![](/files/wsdPg6NmXLvKHMJXKTn5) ## 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. ![](/files/pjV4Ebx7nuHdtIwE8GSn) 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.md). 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

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.servoy.com/guides/get-started/connect-to-a-data-dource.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.