Prerequisites
In order to understand the content of this lesson, make sure you watched the following lessons:
Introduction
In almost every Web application, users come across a form where they are supposed to fill in some information. In WebRatio Platform, forms are handled by a dedicated View Component named "Form". In this lesson you learn how to use the "Form" component to model and configure a form with fields.
Form Component
The "Form" component is a "View Component" consisting of "Fields", "Selection Fields", and "Multi Selection Fields" that show an input form to the user. By using the "Form Component" you can model forms consisting of either a single field, such as a google-like search form, or several fields, which can be used for data management or a complex search.
How to Add a Form Component
Let's assume you want to create a "Form" allowing the user to search for employees. For this form example, we will continue working with our "CRM" web project. We have already created the "Sales Manager" site view containing the "Employees" area and the "Search Employees" page, where we are now going to create a freely configurable "Form" component that does not use "Data Binding".
To add a "Form" component to a Page, select the "Form" component from the "View Components" section of the toolbar and click inside the page. A best practice is to give a meaningful name to each object in your project to make it easier to recall the element's purpose. Double-click on the default name to change it. Change the name in "Search Employees".
Form Component and Field Types
You can add three different types of fields to the "Form" component: "Fields", "Selection Fields" and "Multi Selection Fields".
Field
A "Field" is a View Component Part allowing free input from the user. A "Field" can be typed and this information is used to automatically validate the value provided by the user. In a form used for searching employees' information, examples of fields are "First Name", "Last Name", "Email" and "Birth Date".
Selection Field
A "Selection Field" is a View Component Part allowing the user to select one item from a list. Selection Fields are composed of Slots. By default, two Slots are available for defining the label and value of the list items.
In a "Form" related to employees, an example of "Selection Field" is the "Company" drop-down menu. A "Selection Field" must be preloaded in order to show the options list to the user. Usually the "Selection Field" has a set of labels to let the user choose the desired option. Each of these labels can be associated with a value used by the Web application in its business logic. For this reason, you need to bind two different items of information on the "Selection Field": one for the "Label" and one for the "Output". This is generally done by using the slots.
A "Slot" is a View Component Part that can be included in a "Field", "Selection Field", or "Multi Selection Field", for preloading values. A "Slot" can be of type "Label" or "Output". A Label Slot shows the corresponding values to the user; an Output Slot provides the corresponding values as output of the "Form" Component. When you add a Selection Field, WebRatio Platform creates two implicit slots that let you bind the two items of information. You are free to change the structure of the "Selection Field", manually adding "slots" to it.
Multi Selection Field
A "Multi Selection Field" is a View Component Part allowing the user to select one or more items from a list. "Multi Selection Fields" are composed of Slots. When you add a "Multi Selection Field", WebRatio Platform creates two implicit Slots that let you bind the two items of information. You are free to change the structure of the "Selection Field", manually adding slots to it.
An example of "Multi Selection Field" in a "Form" for searching employees is the list of checkboxes that allow the user to select the employees by using one or more roles at the same time. As for the "Selection Field", the "Multi Selection Field" must be preloaded in order to work properly. The "Multi selection Field" has the same structure as the "Selection Field".
Entity-Based Form and Data Binding
The "Form" component can be used in two different ways: it can either refer to an object of the Domain Model becoming "Entity-based", or it can be freely configured by adding fields to it one by one. When you specify the "Data Binding" by choosing a Domain Model object, the "Form" component is Entity-based and it references attributes and relationships of the selected Entity in order to create its own fields.
In case of an Entity-based "Form" component, you can use the "Entity Fields Wizard" to design the Form. The "Entity Fields Wizard" is an automatic procedure that helps to add "Fields" to the "Form" component. Let's see how to use it.
How to Add Fields Having Data Binding
For the "Entity Fields Wizard" example, we will continue working with our "CRM" web project. We have already created the "Sales Manager" site view containing the "Employees" area and the "Employees Management" page, where we are now going to create an example of "Form" component using "Data Binding". To add a "Form" component to the Page, select the "Form" component from the "View Components" section of the toolbar and click inside the page. Type a meaningful name for the element, such as "Employee Data".
In our example the form is strictly connected to the "Employee" entity and so it's possible to use the wizard to define its Field. To open the "Entity Fields Wizard", right-click on the "Form" component and select the "Entity Fields Wizard…" option. The first step of the wizard requires you to select the Entity, so from the "Entity Selection" dialog select the "Employee" entity, and press the "Next" button to proceed to the next step. Now you have to choose which Attributes and Relationship Roles are to be added as input fields inside the Form.
Each selected Attribute is going to be added as a "Field". The selected Relationship Roles are going to be added as "Selection Fields" or "Multi Selection Fields" according to their cardinality. The "one-to-many" Relationship Roles are going to be added as "Selection Fields", the "many-to-many" Relationship Roles are instead going to be added as "Multi Selection Fields".
For our example let's select the "Name", "Surname", "Gender", "Company", "Creation Date" and "Role" Attributes. Press "Finish" to confirm. Move to the Outline View and expand the "Form" Component node in order to see all the "Fields" and "Selection Fields" created through the wizard.
Free Configured Form
As we said at the beginning of this lesson, a "Form" component can reference a Domain Model object through the concept of "Data Binding". However the "Data Binding" is not mandatory. When you don't specify a "Data Binding" you can model a Form having fields not strictly related to an Entity. Let's see how to use it.
How to Add a Field
Let's suppose that you want to model a "Form" to search Employees by their names. To add the "Name" field, right-click on the "Form" component and choose the "Add" an then "Field" option. The Field will be shown as a child of the "Form" component inside the "Outline View".
Move to the "Properties View" to configure the "Field". Type a meaningful name for the field, such as "Name", and choose the data type for the field by selecting an option in the "Type" dropdown list. In our example, let’s select the "string" option.
How to add a Selection Field
Let's suppose you want to let the user search for employees by providing also the company in which they work. We then need to add a "Company" selection field to the "Form" omponent. Right-click on the "Form" Component, choose the "Add" and then "Selection Field" option. The "Selection Field" will be shown as a child of the "Form" Component inside the Outline View.
Move to the Properties View to configure the "Field". Type a meaningful name for the Selection Field, such as "Company" and choose the data type for it by selecting an option in the "Type" dropdown list. In our example let's select the "string" option.
How to add a Multi Selection Field
Let's suppose you want to let the user search for employees by providing the role the employees have in the company. We then need to add the "Role" Multi Selection Field to the "Form" Component. Right-click on the "Form" Component, choose the "Add" and then "Multi Selection Field" option. The "Multi Selection Field" will be shown as a child of the "Form" Component in the Outline View.
You can now directly type the name for the "Multi Selection Field", type "Role". Choose the data type for it by selecting an option in the "Type" dropdown. In our example let's select the "string" option.
Field, Selection Field and Multiselection Field common properties
"Fields", "Selection Fields" and "Multi Selection Fields" have a set of properties that let the user configure them as desired. Some properties are shared by all field types while other properties are specific. All properties can be configured through the Properties View. Let's start explaining the common properties, which are "Id", "Name" and "Type".
The "ID" is the Unique identifier used by WebRatio Platform in order to let you search elements in the Web Project. Every time you add a "Field" of any type to a "Form", the "ID" is automatically set by WebRatio Platform and cannot be changed.
The "Name" corresponds to the label shown to the user for specific input, and is mandatory.
The "Type" specifies the kind of information the user must enter into the input field. For example, a "Field" of "date" type forces the user to enter a valid date. The "Type" also defines the way in which the Field is shown to the user. For example, a "Field" of "date" type will be displayed as an input text with a calendar icon next to it; when the user presses the icon he sees a calendar widget in which he can select the desired date. Finally, the "Type" associates a default validation on the Field value, which means that if the user provides a value that is not a "date", he will get an error message.
On a "Field", it's possible to specify in more detail which information the user must provide. This is the aim of the "Content Type" property. For example, for a "Field" of type "text", you can choose whether the text is "plain text" or "HTML text". In the latter case, the user will see a rich text editor in the page for writing the desired text.
Data Types List
There are several options for the "Type" property. This is the full list of available types with an example for each. Take your time to look at this list. When you are ready to proceed, press "Next".
Field Specific Properties
A "Field" View Component Part has a set of specific properties in addition to the "Id", "Name", "Type" and "Content Type" property that lets you configure the field exactly as you desire.
When a "Field" is created using the "Entity Fields Wizard", "Name", "Type" and " Content Type" properties have a default value that is inherited from the referenced "Domain Model" object. In addition, the "Attribute" property contains the Domain Model object reference.
The "Modifiable" property determines whether the user can fill in a value in the Field. Usually in the latter case, the "Field" is not shown empty to the user but with an initial value that cannot be changed. An example of non-modifiable Field is the "Creation Date" of the employee. This information usually is automatically retrieved by the Web Application and you may want to show this information to the user in a Field, without letting him change it.
The "Hidden" property specifies whether you want the Field to be shown in the Form. A Hidden Field usually has an initial value because you want to provide the field value to the Web Application business logic, but you don't want to show the information to the user or let him modify it. An example of a Hidden Field is the field containing the "ID" of the employee to be updated, which is not a meaningful piece of information for the user but is necessary to save the changes to the employee information.
In both previous examples you may want to provide an initial value. This is the aim of the "Preloaded" property. When this property is set, you can bind information to the Field and provide a value to it. The result is that when the user sees the form, the field is not empty but contains a value.
In order to pass the information to the preloaded field you have two options: you can either provide a constant value or you can use a different "View Component" in order to retrieve the desired information and pass it to the field. Let's see how to model both cases.
How to Preload a Field with a Constant Value
Let's go on working on the "Form" for managing the employee's information. Through the "Entity Fields Wizard" we added the "Creation Date" Field, which keeps track of the date in which the employee is created for the first time. We want to preload this field with this specific date - "January 1st, 2014", giving the user the possibility to change it.
To provide a default value to the field, we need to add a "Slot" to it. Right-click on the "Creation Date" Field from the Outline View, choose the "Add" and then "Slot" option. The new "Slot" will be added as a child of the Field in the Outline View. Select it and move to the Properties View. From the Properties View, set the name for the Slot, for example "Default Value", and write a value for it, type "2014-01-01".
Check that the "Modifiable" property is enabled in order to let the user change the default value.
To check that the feature is working, save and launch the generation procedure using the "Generate and Run" button.
How to Preload a Field with a Dynamic Information
The previous example is not a realistic situation, because usually the "Creation Date" is the current date, which changes day by day and so cannot be set with a constant value. Every time you need to preload a "Field" with dynamic information, you must use another "View Component" and a "Data Flow" that connects it to the "View Component" of your choice. In our example we can use the "Time" Component, which is available in the "Utility Components" section of the toolbar and is able to retrieve the current date.
Select the Component from the toolbar and place it inside the page. Write a name for the component, for example "Today". Then add a "Data Flow" connecting the "Time" Component and the "Form" Component. Click on the "Flow" section of the toolbar, select the "Flow", first click on the "Time" Component and then click on the "Form" Component.
Select the "Creation Date" Field from the Outline View and move to the Properties View. Check the "Preloaded" property to indicate that the "Field" is preloaded with dynamic information. This property also allows you to bind information to the Field. Expand the "Creation Date" Field. The "Slot" created for the previous example is not necessary anymore, so you can right click on the Slot from the Outline View and choose the "Delete" option. Press "Yes" to confirm.
Now, today's date is retrieved by the "Time" Component and must be provided to the Field. Open the "Parameters Binding" dialog by double clicking on the "Data Flow", uncheck the "Enable Default Binding" property and bind the "Current/Input Date" value provided by the "Time" Component with the "Creation Date" Field. Press "OK" to confirm your choice.
This will show today's date inside the field, giving the user the possibility to change this value. To check that the feature is working, save and launch the generation procedure using the "Generate and Run" button. Remember that, even if in this example we used the "Time" Component to preload a "Field", this is not mandatory. You can use any other "View Component" to provide information to the "Field".
Selection Field and Multi Selection field specific properties
"Selection Fields" and "Multi Selection Fields" have a set of specific properties in addition to the "Id", "Name", "Type" and "Content Type" property that let you configure the input exactly as you desire.
As for "Fields", "Selection" and "Multi Selection Fields" created using the "Entity Fields Wizard" inherit from the referenced Domain Model object a default value for "Name", "Type" and "Content Type". In addition, the "Relationship Role" property contains the Domain Model object reference.
In order to understand the purpose of the additional properties, which are "Preselected Value" and "Split Output", you need to know how these two Field types work. "Selection Fields" and "Multi Selection Fields" must be preloaded in order to work properly. The preload involves the definition of the available options list, from which the user can select the desired value. It’s possible to model a fixed set of options or a dynamic one. In both cases you may want to set a default choice and then let the user change it. This is the concept of "pre-selection". Let’s see now how to preload a "Selection Field" or a "Multi Selection Field".
How to Preload a Selection Field with Fixed List
Let's suppose that you want to use a "Selection Field" to assign the gender of an employee. In the form we have modeled before, the "Gender" Field was created as a Field, since it references a Domain Model Object Attribute. You can convert this field into a "Selection Field". Right-click on the Field from the Outline View and select the "Refactor" and then the "Convert to.." option. In the opening dialog select the "Selection Field" option and press "OK" to confirm.
In this case you already know the list of all the available options for the "Selection Field", which are "Male" and "Female". To define the fixed option list for the Selection Field, right-click on it in the Outline View, choose the "Add" and then "Slot" option. Enter a meaningful name for the "Slot", like "Gender Options". Then in the "Value" property you have to write down the options list. Use the "pipe" character to separate each option. The values provided in this case can be used both as "Label" and as "Output", so check both properties.
To check if the feature is working, save and launch the generation procedure using the "Generate and Run" button.
How to Preload a Selection Field with Dynamic List
In some cases the option list for a Selection Field depends on the information stored in the application database. Let's consider our "Company" Selection Field. The aim of the Field is to assign the Company for which an Employee works. The list of companies is stored in the database, so it's not possible to use a fixed list. We need to provide a dynamic list. As discussed before for preloading a Field, you can use a View Component and a Data Flow to retrieve the options list and pass it to the Selection Field.
The most-used View Component for retrieving the options list is the Selector Component. This View Component does not have a layout and so the data retrieved is not shown to the user. Select the "Selector" Component from the "Utility Components" section of the toolbar and place it inside the page. Give it a meaningful name, like "Select Companies"; then move to the Properties View. Press the "Select" button of the "Entity" property to choose the "Company" Entity, then press the "OK" button to confirm. To sort the list, press the "Sort" button of the "Sort Attributes" property and set the order you desire. For example, select "ascending" for the "Name" Attribute by clicking on the "Order" field in the dialog. Then press the "OK" button to confirm.
Now you need to preload the Selection Field, so add a Data Flow connecting the Selector Component and the Form Component. Double-click on it to open the Parameters Binding dialog and then uncheck the "Enable Default Binding" property. On the right part of the dialog you can see three different input parameters referring to the "Company" Selection Field. To preload the option list, we use the two input parameters named "EmployeeToCompany [label]" and "EmployeeToCompany [output]". The "EmployeeToCompany [label]" Input Parameter represents the options list shown to the user, while the "EmployeeToCompany [output]" Input Parameter represents the options list used by the Web application. Bind the "Name" Attribute of the Company with the Label of the Selection Field, and the "VAT Code" Key Attribute with the Output. Press the "OK" button to confirm your choice.
To check that the feature is working, save and launch the generation procedure using the "Generate and Run" button.
How to Set a Constant Pre-Selection
Now that you have the Selection Field to assign a company to an employee, you can also set the preselected value for this Field. The preselected value is the default value that is shown when the user accesses the page.
Let's see how to set a constant preselected value. Select the Form Component from the page, and from the Outline View select the "EmployeeToCompany" selection field and move to the Properties View. The "Preselected Value" property lets you set a predefined value for a Selection Field. The value that you enter here must be contained inside the list of preloaded outputs, otherwise your value is ignored.
Let's suppose that you want to preload the Selection Field with the company that has "VAT Code" equal to "1". Type "1" for the "Preselected Value".
To check that the feature is working, save and launch the generation procedure using the "Generate and Run" button. Using the "Preselected Value" to set the preselection for a Selection Field is highly discouraged since it assumes that you know the value at design time, which is not true most of the time. It's better to use the dynamic preselection.
How to set a dynamic pre-selection
Another option to set the preselection of "Selection Fields" is to use the "Preselected" target shown in the "Parameters Binding" dialog of a flow reaching the "Form" component. In this way you guarantee that the value can be read from the model by looking directly at flows, and above all you can provide dynamic values to this slot.
Always remember that the provided value must be consistent with the values that you pass to the output target, and of course it also needs to be included in that list of values.