Simple form

In this tutorial we continue with the modal that was made in the tutorial: button with modal.
After finishing this tutorial, the modal will contain a form with four input fields. It will look like the picture below:

form example
Add modal outlet

Several blocks offer the option to add an identifier via Set Outlet.
The outlet is an option. We will use it for this modal, so we can refer to it when we need to close the modal.
Type registermodal in the Set Outlet field.

set-outlet
outlet-filled
Add "div" for errors

In one of the next tutorials, we are going to display an error message in our modal, if the user does not fill the input fields correctly. To display the error message, we will make a small change in the function that opens the modal. In the openRegisterModal function, include a div element, that reserves the place where error messages will be shown.

Add the div element to the header. It is also possible to add it to the body, but if a form has a lot of input fields, the error message may not be visible if the user has scrolled below it. To add an extra element in the modal, disconnect the heading: h3 block first, select a ui: multiple block from the Header, add a ui: grid row to the multiple, pull out a ui: grid column from the row, and connect the heading: h3 block to this column. On the second pin form the ui: multiple pull out a utilities: div block.

modal function with div

The div block does not get content at this point in the program. In order to use it for the error messages, we need to define an outlet. Type errormessage in the outlet field. After these changes the blueprint looks like the picture above.

Create a form element

A form element is a wrapper that contains all your form input fields. You create it by pulling out the Body pin with the left mouse button. Type form in the menu searchbar and choose the form element.

menu-form

The form element itself is not a visible item in the frontend page. It is used to retrieve the data input when we save it to the back-end. A form element always needs an outlet. Please type registerform in the outlet field of the form element block.

The form element block has two in-pins: the Form Prefill pin and the Form pin. The prefill option is necessary if you want to edit existing data in your form. We will not do that here, but get back to that in another tutorial. The Form pin is where we will start adding the frontend input fields to the form. To get these in a good layout, you first need to understand using grid elements.

How to use the grid layout

In order to get a basic frontend page layout, Rual has Bootstrap built in, if you don't want to use your own custom HTML template. For the Bootstrap grid you first need to define a container. You can choose between grid:fluid container a full width container that adapts to the width of the browser, or grid:container that has a limited width, so you may see it centered on some browsers.

Select the grid:fluid container. The container has to wrap all the rows that you want to use. In order to add multiple rows to the container, click on the + to add new Content pins. Next step is to pull out a grid:row block from each Content pin. The form will consist of 4 rows in total.

four-rows

To add the columns, we need an extra Content pin from the row block. You can create extra pins by pressing the + below the first Content pin, and remove them by pressing the -. Now pull out two grid:column blocks.


Setting the column width

Next the columns must get the right width. By default, every new column block has a col-12 attribute, which is full width, since the Bootstrap grid has a maximum of 12 columns. By clicking on the Attributes field, you can alter the col-span, and add many other styling and classes. For now we will only change the column width. For the first column, set it two col-4 by selecting the 33% width in the dropdown menu. The second column needs to be set in a similar way to col-8. Do this by selecting 66% in the dropdown menu. Setting the width for the Class: extra small will automatically apply to larger devices as well.

add-columns
set-column-width
Copying blocks

The grid for the first row is now complete. Since we want to have four rows in the form with the same column widths, the easiest thing to do now is copy the columns from the first row to the other rows. If you pull out a new block, the default styling will appear. However if you copy a block, your styling will be copied too.


To select multiple blocks, hold down your right mouse button
or use ctrl+left mouse button.

An orange line will appear around the blocks so you can see what's your selection. To copy use ctrl+c, move to the new location and use ctrl+v to paste. You can paste the same selection multiple times.

This sets the grid layout for the input fields. If you open the modal in the frontend, you will still see nothing. The only thing grid blocks do is set the structure. Next step is to fill the columns with our form fields.

Add form input fields

Each row now has two columns. The columns appear in the frontend from left to right, and in the blueprint from top to bottom. The left column in the modal only contains text. In another tutorial we will look into using text that can be translated. We will use non-translatable text here to keep things simple. Pull out the Content pin from the column block. Select custom text and type Your first name: in the custom: string block. See left image below.


The Field pin contains the name for the field in the data storage.

The right column will contain the input field. Pull out the Content pin from the column block and select Form: Text Input. Now pull out the Field pin and select fields: get single. Type firstname in the search field. If the field does not exist yet, you can create it with enter If you make a new field definition, choose "string, value" as the type for this field. If the field definition already exists in your entity, just select the field from the list using enter.

add-form-label
add-form-input

After setting up the first row, the next three rows are more or less similar. Add a row just like the first one to get the last name in the form. Continue to the third row, and create a text input field for the phone number copying what you see in the picture below. On the fourth row, we will use a different input field.

form fields

The last field in the form is a date field. Rual Studio has many different formats built-in, and date is one of them. Every date in Rual is saved in Unix timestamp format. This means that it records the time in seconds, and you can choose later in which format you want to show it. Select the Form: Date input and pull out the Field pin to select the field that you will use for saving the data.

add date input field
Add a save button to the form

Of course the whole idea of a form is to do something with the data the user has entered there. In this case we will save the data to a new storage. To do that we need a function, and to get to that function we need something to trigger it. Please refer to the previous tutorial: button with modal if you want to look up how to make a button and add a left click event to create a new function saveRegistration, as shown in the picture below.

save button

Check the form in the frontend page

If you haven't done so already, press the save your changes button and view your page in the frontend. You can do this by typing the url in the browser, or by going to the page block and pressing view. Click on the Register button and your modal with the new form will open!

In the next tutorial: save form input you will learn how to create a new document in a data storage with the form input.