Validation of Editable Input Fields in Tables

Overview

Web Center supports validation of editable input fields in tables.A validation may involve just a single table cell, or several table cells within the same row.A validator may for example make sure that a date lies within a specified range, or that some dates are in proper order.

Samples

Date Validations

Let’s say we have a table with columns for editable start dates and end dates.We want to make sure that

Dates are entered in the correct format.
Newly entered or changed dates don’t lie in the past.
The start date always precedes the end date.

To achieve this we add three validators to the table’s checks attribute and assign some identifying columns to the table’s namingColumns attribute.The attributes are described in greater detail in the following chapters.

<form-property name="assignedGroups" ...
   type="com.siemens.webMgr.model.DirectoryEntryBean[]"
   checks="date:assign.dxrStartDate:['TODAY']:lowerBoundedDate;
           date:assign.dxrEndDate:['TODAY']:lowerBoundedDate;
           dates:assign.dxrStartDate,assign.dxrEndDate:[true]:beginEndDateLess"
   namingColumns="$displayName,targetSystem.cn">
    <data-property name="$displayName" type="java.lang.String"/>
    <data-property name="description" type="java.lang.String"/>
    <data-property name="targetsystem.cn" type="java.lang.String"/>
    <data-property name="assign.dxrStartDate" type="java.util.Date"
		    label="ldap.attribute.dxrStartDate" width="8%"
                   readonly="false" sortable="false"/>
    <data-property name="assign.dxrEndDate" type="java.util.Date"
		    label="ldap.attribute.dxrEndDate" width="8%"
                   readonly="false" sortable="false"/>
</form-property>

Time Validations

Now let’s consider a table with columns for editable start times and end times. We want to make sure that

Times are entered in the correct format.
Newly entered or changed start times don’t lie in the past.
The start time always truly precedes the end time.
The end time is no later than the last day of 2020.

To achieve this we add three validators to the table’s checks attribute. The attribute is described in greater detail in the following chapters.

<form-property name="users" ...
   type="com.siemens.webMgr.model.DirectoryEntryBean[]"
   …
   checks="time:startTime:['NOW']:lowerBoundedTime;
           time:endTime:['','2020-12-31T23\:59Z']:upperBoundedTime;
           times:startTime,endTime:[true]:customStartEndTime">
    <data-property name="$displayName" type="java.lang.String"/>
    <data-property name="startTime" type="java.util.Date"
		    label="ldap.attribute.startTime"
                   readonly="false" cellRenderer="time"/>
    <data-property name="endTime" type="java.util.Date"
		    label="ldap.attribute.endTime"
                   readonly="false" cellRenderer="time"/>
</form-property>

Configuration

Checks

The checks attribute accepts the semicolon-separated list of validators to be applied to the table.

Each validator consists of

The name under which the validator is registered.
The data property names of the table columns the validator applies to.
The validator arguments (a Javascript array, which may be empty).
The key for the tooltip text (optional).

The validator components are separated by colons.

Sample

In the above sample, the first validator checks the format of start dates and rejects start dates in the past:

date:assign.dxrStartDate:['TODAY']:lowerBoundedDate;

The second validator performs the same checks for end dates:

date:assign.dxrEndDate:['TODAY']:lowerBoundedDate;

The third validator makes sure that a start date precedes the corresponding end date:

dates:assign.dxrStartDate,assign.dxrEndDate:[true]:beginEndDateLess

Naming Columns

If a user tries to submit a form with an invalid value in a table cell, Web Center displays a corresponding error message. In order to make clear which entry (row) in the table the message refers to, the message includes the values of one or more table cells that identify the entry.

The attribute namingColumns contains the names of the data properties that identify an entry, separated by commas.

By default, only the value in the first column is displayed.

Sample

In the above sample, the groups are identified by their name and their target system, so these values should be displayed in error messages:

namingColumns="$displayName,targetSystem.cn"

Validators

Single-Property Validators

A single-property validator consists of

A validator name; the name must be a valid Javascript variable name; required.
A list of validator arguments; optional.
A Javascript object with member:
- check – A function that checks the validity of a value. The function accepts the value as its first argument, and the validator arguments as additional arguments. The function must return “false” if the check fails, and “true” otherwise.
Tooltip texts; per supported language; optional. Tooltips may contain placeholders to be replaced with the actual validator arguments at runtime. “${0}” is replaced with the first argument, “${1}” with the second, etc. The placeholders for date arguments are “${0d}”, “${1d}” etc.

Notes:

A custom tooltip must be assigned to
```
messages.custom.texts.tooltip.format.<validator name>
```
You can define a separate tooltip for Firefox. This is sometimes useful for tooltips including new lines, since Firefox and Internet Explorer render new lines in a different way (Firefox just ignores new lines):
```
messages.custom.texts.tooltip.format.ff.<validator name>
```
You can use single-property validators for form input fields to validate editable table cells, like for example date. Note that the regular expression is ignored. Only the check function is called.
Register custom validators via function validators.register.

Mutliple-Property Validators

A multiple-property validator consists of

A validator name; the name must be a valid Javascript variable name; required.
A list of validator arguments; optional.
A Javascript object with member:
- check – A function that checks the validity of the property values. The function accepts the following arguments:
  - The nodes to be checked (a Javascript array). Each node is an object with the following fields:
    
    id - The HTML id of the table cell.
    
    value – The value to be checked.
  - The second argument is always true since table validators are not triggered by key up events.
  - The optional validator arguments.
    
    The function must return an object with two fields named “ok“ and “inv“. “inv“ is an array containing the indexes of the nodes to be added to the list of invalid properties, while “ok“ contains the indexes of the nodes to be removed from that list. Any property not referenced in the arrays is left untouched.
    
    In addition to that, the function may also return tooltip keys for invalid cells. The keys have to be passed in field “msg“ of the returned object; The n^th item in “msg“ corresponds to the n^th node. The tooltips override the tooltips for the validator defined below.
Tooltip texts; per supported language; optional. You can define a single tooltip for all properties, or different tooltips per property. Tooltips may contain placeholders to be replaced with the actual validator arguments at runtime. ${0} is replaced with the first argument, ${1} with the second, etc. The placeholders for date arguments are ${0d}, ${1d} etc.

Each custom tooltip must be assigned to
```
messages.custom.texts.tooltip.format.<tooltip name>
```
You can define separate tooltips for Firefox. This is sometimes useful for tooltips including new lines, since Firefox and Internet Explorer render new lines in a different way (Firefox just ignores new lines):
```
messages.custom.texts.tooltip.format.ff.<tooltip name>
```
You can use multiple-property validators for form input fields to validate editable table cells, like for example dates. In complex cases, however, it might be more appropriate to write a specific validator; for an example, see validator certDates.
Register custom validators via function validators.register.