Tutorial: Forms and Validation

Update history: last updated January 2011 for WaveMaker Version 6.2. Update for WaveMaker version 6.3 is in progress.

This tutorial section will show how to work with forms and editors to validate data, set default values and work with related data.

Click here for a PDF version of this tutorial.

This tutorial will take approximately 15 minutes to complete.

Database tables can have relationships with one another. For example, the hrdb database for the EmployeeApp has multiple relationships, including:

• Employee Manager Relationship. Each employee manages one to many subordinates. This is called a one-to-many relationship. In the data model, this relationship is represented by a foreign key column in the employee table that stores the id of that employee's manager.
• Vacation Request Relationship. Each vacation request must have a related employee. This is called a one-to-one relationship (each vacation must have one related employee). In the data model it is represented as a foreign key in each row of the vacation table containing an employee id.

Before you start: Create new project

To start, create a new project and import the built-in "hrdb" database. Refer to the previous tutorials for more information on how to do this.

1. Create a new project.
2. Set the project name to: ValidationApp
3. Set the project theme to wm_default
4. Set the project template to the Tabs Template
5. Import the hrdb database

Validate text input

A form contains an editor for each column in a database table. Here are some things to know about data editor validation:

• All editors validate the input data based on the data type. For example, a number editor will not allow the user to enter anything other than the digits 0 to 9
• The developer can set editor properties to add additional validation, such as minimum and maximum values for a number or maximum length for a text string
• The developer can also add help and error messages to display to the user

To validate text input, follow these steps:

1. Drag the Department database widget onto the canvas.
   
   
2. Select the Traditional LiveForm option and click OK.
3. Select the LiveForm Name editor, which is located on the lower half of of the web page.
   
   
4. Examine the Properties for the Name editor widget.
   
   Here is a brief description of the Common editor properties:
   • name: name of widget
   • showing: if unchecked, this widget will be invisible
   • formField: this is the name of the database column that this editor is connected to
5. Examine the Editor Options properties for the Name editor widget.
   
   Here is a brief description of the Editor Options properties:
   • readonly: if this is checked, the data value of this editor cannot be changed
   • password: if this is checked, the letters entered by the user will not be visible on the screen. This is useful for password fields.
   • maxChars: specifies the maximum number of characters a user can enter into this editor
6. Set the maxChars property for the editor to 10
7. Click the Run button.
8. In the running application click the New button at the bottom of the Department form to create a new department
9. Click in the Name field.
10. Try to enter a name longer than 10 characters. Note that the text editor refuses to accept more than 10 characters

Validate numeric input

A form contains an editor for each column in a database table.

To validate a numeric input, follow these steps:

1. Now select the Budget editor in the canvas
   
   
2. Set the promptMessage property for the Budget editor to: Enter a budget between 1 and 100.
   This message will be displayed as a tooltip when this editor is selected.
   
   
3. Set the minimum property to: 1
4. Set the maximum property to 100
5. Set the rangeMessage property to: Number out of range.
   This message will be displayed when the user tries to enter a number less than one or greater than one hundred
   
   
6. Click the Run button.
7. In the running application click the New button at the bottom of the Department form to create a new department
8. Click the Budget editor in the form. Note the tooltip that appears when the Budget field is entered
   
   
9. Enter the number 200. Note that an error message appears
   
   

Set default values

A form for a database widget takes its value from the currently selected row. The defaultInsert property of an editor allows the developer to specify what the default value should be.

To set the defaultInsert property for the budget editor, follow these steps:

1. Now select the Budget editor in the canvas
   
   
2. Set the defaultInsert property for this editor to: 50
   Note: You may have to scroll the property list to find the defaultInsert property.
   
   
3. Click the Run button.
4. In the running application click the New button at the bottom of the Department form to create a new department
5. Note that the value for Budget was automatically set to 50
   
   

Set default date

The defaultInsert property for each live form editor provides a way to set the value for that property when creating a new database row.

To set a date editor to default to today's date, follow these steps:

1. Select Tab2 in the canvas
2. Drag a Vacation database widget into Tab 2.
   
   
3. Select the Traditional LiveForm and click OK.
4. Select the Startdate editor in the form for the vacation database widget
   
   
5. In the Property panel defaultInsert property, click the bind button
   
   This brings up the Binding Editor
6. At the top of the Binding Editor, select the Expression radio button. This allow you to enter simple Javascript commands to set the defaultInsert value
7. Enter the Javascript command: new Date().
   
   This creates a new date with today's date.
   
8. Click the Bind button to close the Binding Editor. Note that the binding shows up in the defaultInsert property.
   
   
9. Click the Run button.
10. Click on Tab 2 to bring up the vacation database live form.
11. Click the New button to create a new vacation entry
12. Note that the default start date is set to today's date
    
    

Forms With "To-One" Relationships

A RelatedEditor is a specialized select editor for use in LiveForms. A RelatedEditor is used to set relationships between tables, such as setting the employee relationship for a vacation request. Here are some things to know about RelatedEditors:

• RelatedEditors for relationships that are required by the database are generated automatically (technically, required relationships are relationships where the foreign key value is not allowed to be null).
• RelatedEditors for optional relationships can be added by dragging a RelatedEditor widget into the appropriate LiveForm and setting the formField property.
• Each RelatedEditor is a container widget that contains a lookup editor in the case of a "to-one" relationship and a grid in the case of "to-many" relationship

To set the default value for a RelatedEditor in a LiveForm, follow these steps:

1. Click on Tab 2 to bring up the vacation database widget
2. Click on the "Employee (lookup)" editor
   
   
3. Make sure that that Property panel shows that the currently selected widget is employeeLookup1. This is the lookup editor located inside the RelatedEditor
   
   
4. Press the Escape key to select the RelatedEditor widget that contains employeeLookup1
   
   Note: pressing the Escape key selects the parent widget.
   
5. Examine the Properties for the RelatedEditor widget.
   Here is a brief description of the common Editor properties:
   • name: name of widget
   • editingMode: the options are lookup, which is done using a select editor; read only, which does not allow the relationship to be changed; and editable subform, which allows editing of individual fields in the related table.
   • formField: name of relationship set by this RelatedEditor. Typically, this will be the table name of the related table

Forms with "To-Many" Relationships

A RelatedEditor for a "To-many" relationship shows data from related tables in a grid. Here are some things to know about RelatedEditors for a "To-Many" Relationship:

• A RelatedEditor for a "To-many" relationship shows all of the rows in the related table which are associated with the selected row. For example, it can show all of the vacation requests for a particular employee.

To add a RelatedEditor to show all of the vacation requests for a particular employee, follow these steps

1. Select Tab 3 in the canvas
2. Drag an Employee database widget into Tab 3
3. Select the Traditional LiveForm and click OK.
4. Now drag a RelatedEditor into the Employee Details form
   
   
5. Set the formField property for the RelatedEditor to "vacations"
   
   
6. Note that the RelatedEditor now contains a grid with all the vacation requests for the currently selected Employee
   
   

Set RelatedEditor default value

The defaultInsert property for a LiveForm's RelatedEditor provides a way to set the value for that property when creating a new database row.

To set the default value for a RelatedEditor in a LiveForm, follow these steps:

1. Click on Tab 2 to bring up the vacation database widget
2. Click on the "Employee (lookup)" editor
   
   
3. Examine the Properties for the lookup widget.
   
   
4. Now scroll down to view the Editor Data properties
   
   Here is a brief description of the Editor Data properties::
   • displayValue: this is the value displayed by default
   • dataValue: this is the data value returned by the widget
   • emptyValue: this is the value returned by the widget if the user doesn't enter anything (technically, this is the value returned for NULL input)
   • defaultInsert: this is the default related data to use when creating a new database row
5. Click the bind icon to the right of the defaultInsert property to bring up the Binding Editor
6. Select the employeeDojoGrid from the widget menu
   
   This will set the default related employee for a new vacation request to the currently selected employee on Tab 3.
7. Click the Bind Button to accept the binding
8. Click the Run button.
9. In the running application click Tab 3 then click on an employee
10. Select Tab 2 and click the "New" button to create a new vacation request
11. Note that the default related employee for this new vacation request is the employee selected on Tab 3
    
    

Congratulations!
You have completed the Forms and Validation Tutorial.

PDF version of this tutorial

Continue on to Tutorial: Security