Validation

Overview

Web Center provides a built-in validation mechanism to check user input on the client side.Validation samples are:

  • Checking for allowed characters, like letters or digits.

  • Checking for a valid e-mail address or phone number.

  • Checking the range of a number.

  • Assuring that a minimum value doesn’t exceed the maximum value.

  • Assuring that a start date precedes the end date.

  • Assuring that a date lies within a specified range.

  • Assuring that an employee number is specified for internal employees.

On detection of invalid input into a form field, the field is rendered with a red background color, and form submission is blocked. Tooltips inform the user of any conditions input values must meet.

A validation method is implemented by a validator. Validators are implemented in Javascript and executed in the browser, whenever the user presses a key in an input field or changes its value. Therefore, validators should terminate quickly in order not to interrupt the user.

Validators are assigned to specific renderers, which in turn can be assigned to individual form properties, or defined as default renderer for all properties of a given name, type or editor. Note that default renderers also apply to dynamically generated forms used to perform request workflow tasks (like enter attributes activities).

Most validators check the value of a single property, while others cross-check the values of several properties, like the order of a start and end date. You can define a single-property check and a multiple-property check for the same property. You should, however, avoid conflicting checks.

Validators should not check if mandatory fields contain a value since this is already controlled by a respective attribute of form properties and request workflow activity parameters.

Property values are trimmed before being validated, that is any leading and trailing white spaces (like spaces, tabs, carriage returns and line feeds) are cut off.

While Web Center is shipped with a set of predefined validators, you may also provide custom validators.

Validation of editable table cells works a bit differently and is described in a separate chapter of this document.

The next chapters describe in detail how to write validators.To get a first feeling of how it works, take a look at the validator samples in the last chapter.

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 two members:

    • expr – A regular expression that the property values must match; optional.

    • check – A function that checks the validity of a property value; optional.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.

  • 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>

Predefined Validators

fax

The validator applies to form properties of type java.lang.String. It checks if a field value is a facsimile telephone number complying with RFC 2252 – LDAP (v3): Attribute Syntax Definitions. The validator doesn’t accept any arguments.

mail

The validator applies to form properties of type java.lang.String. It checks (rather informally) if a field value is a valid mail address. The validator doesn’t accept any arguments.

print

The validator applies to form properties of type java.lang.String. It checks if a field value is a valid printable string complying with RFC 2252 – LDAP (v3): Attribute Syntax Definitions. The validator doesn’t accept any arguments.

integer

The validator applies to form properties of type java.lang.Integer. It checks if a field value is a whole number. Optional arguments are minimum and/or maximum value.

date

The validator applies to form properties of type java.util.Date. It checks if a day (without time) lies within a given range. Arguments are earliest and/or latest possible date. The arguments can be either specified as specific days (“yyyymmdd”, e.g. “20100101” and “99991231”), or as number of days from today (“TODAY”, “TODAY+10”, “TODAY-365”). The year must lie within 1000 and 9999.

time

The validator applies to form properties of type java.util.Date. It checks if a date (day and time) lies within a given range. Arguments are earliest and/or latest possible date. The arguments can be either specified as specific UTC times (“yyyy-mm-ddTHH:mm:ssZ”, e.g. “2000-01-01T13:00:30” and “2020-12-31T23:59Z”), or as number of days, hours or minutes from now (“NOW”, “NOW+100d”, “NOW-24h”, “NOW-30m”, where “NOW” is the time a user loads a page to enter the time.) The year must lie within 1000 and 9999. Note that the terminal letter “Z” and the seconds part “:ss” in specified UTC times are optional.

Web Center users will see and enter all times in their local time, which is usually different from UTC time. This also applies to the upper and lower time bounds specified here.

Sample Custom Validators

customEmployeeNumber

The validator applies to form properties of type java.lang.String. It checks if an employee number starts with two digits, followed by a dash and two upper case letters.

  • Validator name: customEmployeeNumber

  • Validator arguments: none

  • Javascript object name: custom.employeeNumber

  • Javascript regular expression: /^\d\d-[A-Z][A-Z]$/

  • Javascript function: none

  • Tooltips:

  • English: “Two digits (0-9), followed by a dash and two upper case letters (A-Z).”

  • German: “Zwei Ziffern (0-9), gefolgt von einem Bindestrich und zwei Großbuchstaben (A-Z).“

Define the Javascript object in a custom Javascript file:

var custom = {
    ...
    employeeNumber: {
        expr: /^\d\d-[A-Z][A-Z]$/
    },
    ...
}

Add the tooltips to the object messages.custom.texts.tooltip.format in the custom message files (messages.js):

English message file:

customEmployeeNumber = "Two digits (0-9), followed by a dash and two upper case letters (A-Z)."

German message file:

customEmployeeNumber = "Zwei Ziffern (0-9), gefolgt von einem Bindestrich und zwei Gro\u00DFbuchstaben (A-Z)."

Note that non-ASCII characters must be replaced with their Unicode representations in message files, like “\u00DF” for “ß”.

customUid

The validator applies to form properties of type java.lang.String. It checks if a unique ID contains just digits and upper case letters. In addition to that, the unique ID should not exceed a configurable maximum length. We use a regular expression to ensure that a unique ID contains digits and numbers only, and a Javascript function to check the length.

  • Validator name: customUid

  • Validator arguments:

  • 1st argument: The maximum length.

  • Javascript object name: custom.uid

  • Javascript regular expression: /^[\dA-Z]*$/

  • Javascript function: see below

  • Tooltips:

  • English: “A unique ID must include digits (0-9) and upper case letters (A-Z) only. Its maximum length is ${0}.”

  • German: “Eine eindeutige ID darf nur Ziffern (0-9) und Großbuchstaben (A-Z) enthalten und höchstens ${0} Zeichen lang sein).“

Define the Javascript object in a custom Javascript file:

var custom = {
    ...
    uid: {
        expr: /^[\dA-Z]*$/,
        check: function(value,maxLen) {
            if (!maxLen || maxLen <= 0 || !value)
                return true;
            return value.length <= maxLen;
         }
    },
    ...
}

Add the tooltips to the object messages.custom.texts.tooltip.format in the custom message files (messages.js):

English message file:

customUid = "A unique ID must include only digits (0-9) and upper case letters (A-Z). Its maximum length is ${0}."

German message file:

customUid = "Eine UID darf nur Ziffern (0-9) und Gro\u00DFbuchstaben (A-Z) enthalten und h\u00F6chstens ${0} Zeichen lang sein."
customPhone

The validator applies to form properties of type java.lang.String. It checks if a phone number complies with the format “+<country code> <area code> <local number>” where the country code is one of a list of predefined country codes, while area code and local number are non-empty sequences of digits. The country code list should be passed in as an argument to the validator.

  • Validator name: customPhone

  • Validator arguments:

    • 1st argument: The valid country codes.

  • Javascript object name: custom.phone

  • Javascript regular expression: none

  • Javascript function: see below

  • Tooltips:

  • English: “The phone number format is \"+<Country code> <Area code> <Local number>\". \nValid country codes are: ${0}.”

  • German: “Eine Telephonnummer im Format \"+<Ländercode> <Vorwahl> <Lokale Nummer>\". \nZulässige Ländercodes sind: ${0}.“

Define the Javascript object in a custom Javascript file. The list of valid country codes is expected to be a Javascript array.

var custom = {
    ...
    phone: {
        check: function(value,countryCodes) {
            if (!value)
                return true;
            var m = value.match(/^[+](\d+) \d+ \d+$/);
            if (m) {
                if (!countryCodes || countryCodes.length === 0)
                    return true;
                for (var i = 0; i < countryCodes.length; i++)
                    if (m[1] === countryCodes[i])
                        return true;
            }
            return false;
         }
    },
    ...
}

Add the tooltips to the object messages.custom.texts.tooltip.format in the custom message files (messages.js):

English message file:

customPhone = "The phone number format is \"+<Country code> <Area code> <Local number>\". \nValid country codes are: ${0}."

German message file:

customPhone = "Eine Telephonnummer im Format \"+<L\u00E4ndercode> <Vorwahl> <Lokale Nummer>\". \nZul\u00E4ssige L\u00E4ndercodes sind: ${0}."
customPrime

The validator applies to form properties of type java.lang.Integer. It checks if a value is a prime number between a configurable minimum and maximum value.

  • Validator name: customPrime

  • Validator arguments:

  • 1st argument: The minimum value.

  • 2nd argument: The maximum value.

  • Javascript object name: custom.prime

  • Javascript regular expression: /^[\d]+$/

  • Javascript function: see below

  • Tooltips:

  • English: “A prime number from ${0} to ${1}.”

  • German: “Eine Primzahl von ${0} bis ${1}.“

Define the Javascript object in a custom Javascript file:

var custom = {
    ...
    prime: {
        expr: /^[\d]+$/,
        check: function(value, min,max) {
            if (!value)
                return true;
            var n = Number(value);
            min = min || 2;
            if (n < 2 || n < min || (max && n > max))
                return false;
            if (n === 2)
                return true;
            if (n % 2 === 0)
                return false;
            var maxDiv = Math.floor(Math.sqrt(n));
            for (var i = 3; i < maxDiv; i += 2)
                if (n % i === 0)
                    return false;
            return true;
         }
    },
    ...
}

Add the tooltips to the object messages.custom.texts.tooltip.format in the custom message files (messages.js):

English message file:

customPrime = "A prime number from ${0} to ${1}."

German message file:

customPrime = "Eine Primzahl von ${0} bis ${1}."

Multiple-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 two members:

  • init – A function to initialize the validator; optional. The function is called whenever the validator is assigned to a form property.

  • check – A function that checks the validity of the property values. The function accepts the following arguments:

  • The nodes (form elements) to be checked (a Javascript array).

  • A flag indicating whether the actual invocation was triggered by an onchange or an onkeyup event.

  • The optional validator arguments.

The function must return an object with two fields named “ok” and ”inv”. “inv” returns an array of the indexes of the nodes to be added to the list of invalid properties, while “ok” returns the indexes of the nodes to be removed from that list. Any property not referenced in the arrays is left untouched.

  • 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>.

Predefined Validators

minMax

The validator applies to form properties of type java.lang.Integer. It checks if the values of a list of number properties are in ascending order. Validator arguments are:

  • The property names.

  • The minimum value (false for no minimum).

  • The maximum value (false for no maximum).

  • Whether to check for “less than” (true) or “less than or equal to” (false, default).

    Minimum and maximum value are always checked with <= and >=, respectively.

dates

The validator applies to form properties of type java.util.Date. It checks if the values of a list of date properties (no time components) are in ascending order. Validator arguments are:

  • The property names.

  • Whether to check for “before” (true) or “before or equal to” (false, default).

times

The validator applies to form properties of type java.util.Date. It checks whether the values of a list of date properties (including the time components) are in ascending order. Validator arguments are:

  • The property names.

  • Whether to check for “before” (true) or “before or equal to” (false, default).

Sample Custom Validators

customEmployee

The validator checks the combination of employee type and employee number. An employee number is comprised of a configurable number of digits. The number is required for internal employees, and optional otherwise.

  • Validator name: customEmployee

  • Validator arguments:

  • 1st argument: The names of properties employee type and employee number.

  • 2nd argument: The number of digits for the employee number.

  • Javascript object name: custom.employee

  • Javascript init function: none

  • Javascript check function: see below

  • Tooltips:

  • English: “An employee number is comprised of exactly ${0} digits (0-9). \nThe employee number is required for internal employees.”

  • German: “Eine Mitarbeiternummer besteht aus genau ${0} Ziffern (0-9). \nF\u00FCr interne Mitarbeiter muss eine Nummer angegeben werden.“

Define the Javascript object in a custom Javascript file:

var custom = {
    ...
    employee: {
        check: function(nodes,onChange,numDigits) {
            if (nodes.length < 2)
                return null;
            var empType   = nodes[0];
            var empNumber = nodes[1];

            var v = trimSpaces(empNumber.value);
            onChange && (empNumber.value = v);

            var expr = new RegExp("^(?:[0-9]{"+numDigits+"})$");
            var ok   = v ? expr.test(v) : !empNumber.mandatory;

            if (ok && empType.selectedIndex !== -1) {
                if ("Internal" ===
                        empType.options[empType.selectedIndex].value)
                    ok = v.length > 0;
            }

            return ok ? {ok:[1]} : {inv:[1]};
        }
    },
    ...
}

The function marks the employee number property as invalid if the check fails, and as valid if the check succeeds. The employee type property is neither returned as valid nor invalid.

Add the tooltips to the object messages.custom.texts.tooltip.format in the custom message files (messages.js):

English message file:

customEmployee = "An employee number is comprised of exactly ${0} digits (0-9). \nThe employee number is required for internal employees."

German message file:

customEmployee = "Eine Mitarbeiternummer besteht aus genau ${0} Ziffern (0-9). \nF\u00FCr interne Mitarbeiter muss eine Nummer angegeben werden"

Registering Validators

Web Center provides a Javascript object named validators which controls form field validation. The object keeps a map of validator names to validator objects. Initially, the map is filled with the standard validators provided with Web Center.

Custom validators be registered with the validators object in order to get added to the map. The object provides a registration method:

  • register(validator …​) – Registers one or more validators. The function accepts one or more arguments. Each argument is an array of two items:

  • The validator name.

  • The validator object.

You can for example register your custom validators one by one:

validators.register(["customEmployee", custom.employee]);
validators.register(["customEmployeeNumber", custom.employeeNumber]);
validators.register(["customPhone", custom.phone]);
validators.register(["customUid", custom.uid]);

or all validators in a single step:

validators.register(
    [ "customEmployee", custom.employee ],
    [ "customEmployeeNumber", custom.employeeNumber ],
    [ "customPhone", custom.phone ],
    [ "customUid", custom.uid ]
);

  • Register custom validators from within custom script files (custom.js).

Validation Renderers

A validation renderer uses a validator to check property values.There are a couple of base renderers to derive specific predefined and custom renderers from.As usual, each renderer applies to form properties of a specific type.

As with validators, some renderers validate the values of a single property, while others cross-check the values of multiple properties.

Single-Property Renderers

Single-valued properties have simple types like java.lang.String, java.lang.Integer or java.util.Date.

Base Renderers

formattedText

A base renderer for form properties of type java.lang.String.

<renderer id="formattedText" extends="text"
        altURL="/WEB-INF/snippets/textField/formattedTextField.htm"
        jsURL="/WEB-INF/snippets/textField/formattedTextField.js">
    <renderer-property name="validator" value=""/>
    <renderer-property name="args"      value=""/>
    <renderer-property name="tooltip"   value=""/>
</renderer>

Renderer properties:

  • validator – Accepts the name of a specific text format validator; required.

  • args – Accepts additional arguments for the validator; optional.

  • tooltip – Accepts the last component of the message key for the tooltip.

integer

A base renderer for form properties of type java.lang.Integer. The renderer checks if a field value is a whole number, using the predefined validator integer.

<renderer id="integer" type="java.lang.Integer"
	 defURL="/WEB-INF/snippets/textField/roInteger.htm"
        altURL="/WEB-INF/snippets/textField/formattedTextField.htm"
        jsURL="/WEB-INF/snippets/textField/formattedTextField.js">
    <renderer-property name="validator" value="integer"/>
    <renderer-property name="args"      value=""/>
    <renderer-property name="tooltip"   value=""/>
</renderer>

Renderer properties:

  • validator – Accepts the name of the a number format validator; required. The name of the predefined validator is “integer”.

  • args – Accepts additional arguments for the validator; optional. The predefined validator integer accepts the minimum and/or maximum value.

  • tooltip – Accepts the last component of the message key for the tooltip.

boundedNumber

A base renderer for form properties of type java.lang.Integer. It serves to check number fields with minimum and maximum value. It just adds an appropriate tooltip to its base renderer integer.

<renderer id="boundedNumber" extends="integer">
    <renderer-property name="tooltip" value="boundedNumber"/>
</renderer>
lowerBoundedNumber

A base renderer for form properties of type java.lang.Integer. It serves to check number fields with minimum value. It just adds an appropriate tooltip to its base renderer integer.

<renderer id="lowerBoundedNumber" extends="integer">
    <renderer-property name="tooltip" value="lowerBoundedNumber"/>
</renderer>
calendar

The base renderer for form properties of type java.util.Date without the time component. It ensures that a field value is a date. It sets the validator property but leaves tooltip and arguments unspecified.

<renderer id="calendar" type="java.util.Date"
          defURL="/WEB-INF/snippets/textField/roTextField.htm"
          altURL="/WEB-INF/snippets/calendar/calendar.htm"
          jsURL="/WEB-INF/snippets/calendar/calendar.js">
    <renderer-property name="format"
                       value="application.dateFormat"/>
    <renderer-property name="validator" value="date"/>
    <renderer-property name="args"      value=""/>
    <renderer-property name="tooltip"   value=""/>
</renderer>
boundedDate

A base renderer for form properties of type java.util.Date. It is used to check if a date does not precede the earliest possible date or exceed the latest one. The renderer just adds an appropriate tooltip to its base renderer calendar.

<renderer id="boundedDate" extends="calendar">
    <renderer-property name="tooltip" value="boundedDate"/>
</renderer>
lowerBoundedDate

A base renderer for form properties of type java.util.Date. It is used to check if a date does not precede the earliest possible date. The renderer just adds an appropriate tooltip to its base renderer calendar.

<renderer id="lowerBoundedDate" extends="calendar">
    <renderer-property name="tooltip" value="lowerBoundedDate"/>
</renderer>
upperBoundedDate

A base renderer for form properties of type java.util.Date. It is used to check if a date does not exceed the latest possible date. The renderer just adds an appropriate tooltip to its base renderer calendar.

<renderer id="upperBoundedDate" extends="calendar">
    <renderer-property name="tooltip" value="upperBoundedDate"/>
</renderer>
time

The base renderer for form properties of type java.util.Date that include a time component without seconds. It ensures that a field value is a properly formatted date with time. It sets the validator property but leaves tooltip and arguments unspecified.

<renderer id="time" type="java.util.Date"
		      defURL="/WEB-INF/snippets/time/display.htm"
		      altURL="/WEB-INF/snippets/time/edit.htm"
		      jsURL="/WEB-INF/snippets/time/edit.js"
		      roJsURL="/WEB-INF/snippets/time/display.js">
    <renderer-property name="format" value="ECMASCRIPT"/>
    <renderer-property name="displayFormat"
                       value="application.timeDisplayFormat"/>
    <renderer-property name="editFormat"
                       value="application.timeEditFormat"/>
    <renderer-property name="validator" value="time"/>
    <renderer-property name="args" value=""/>
    <renderer-property name="tooltip" value=""/>
    <renderer-property name="buttonTooltip"
                       value="application.tooltip.time"/>
    <!-- Activate this section for non-editable date input fields -->
    <!--
    <renderer-property name="formatTooltip" value=""/>
    <renderer-property name="formInputReadOnly"
        value="readonly=&quot;readonly&quot; tabindex=&quot;-1&quot;"/>
    <renderer-property name="formInputStyleClass"
                       value="roTextField"/>
    <renderer-property name="tableInputStyleClass"
                       value="roTextField"/>
    <renderer-property name="tableInputReadOnly" value="true"/>
    -->
    <!-- Activate this section for editable date input fields -->
    <renderer-property name="formatTooltip"
                       value="application.timeFormat.tooltip"/>
    <renderer-property name="formInputReadOnly" value=""/>
    <renderer-property name="formInputStyleClass"
                       value="rwTextField"/>
    <renderer-property name="tableInputStyleClass"
                       value="rwTextField rwTime"/>
    <renderer-property name="tableInputReadOnly" value="false"/>
</renderer>

The derived renderers boundedTime, lowerBoundedTime and upperBoundedTime just add appropriate tooltips.

timeWithSeconds

The base renderer for form properties of type java.util.Date that include a time component with seconds. It extends renderer time and just redefines some formats and tooltips:

<renderer id="timeWitSeconds" extends="time">
    <renderer-property name="displayFormat"
                   value="application.timeWithSecondsDisplayFormat"/>
    <renderer-property name="editFormat"
                   value="application.timeWithSecondsEditFormat"/>
    <renderer-property name="formatTooltip"
                   value="application.timeWithSecondsFormat.tooltip"/>
</renderer>

The derived renderers boundedTimeWithSeconds, lowerBoundedTimeWithSeconds and upperBoundedTimeWithSeconds just add appropriate tooltips.

Predefined Renderers

fax

A renderer for form properties of type java.lang.String. It checks if a field value is a facsimile telephone number.

<renderer id="fax" extends="formattedText">
    <renderer-property name="validator" value="fax"/>
</renderer>
mail

A renderer for form properties of type java.lang.String. It checks (rather informally) if a field value is a valid mail address.

<renderer id="mail" extends="formattedText">
    <renderer-property name="validator" value="mail"/>
</renderer>
mailList

A renderer for multi-valued form properties of type java.lang.String[]. It checks if the field values are valid mail addresses.

<renderer id="mailList" extends="stringList">
    <renderer-property name="itemRenderer" value="mail"/>
</renderer>
phone

A renderer for form properties of type java.lang.String. It checks if a field value is a valid phone number. It uses the printable string validator since the LDAP syntax for phone numbers is printable string.

<renderer id="phone" extends="formattedText">
    <renderer-property name="validator" value="print"/>
</renderer>
naturalNumber

A renderer for form properties of type java.lang.Integer. It checks if a field value is a whole number greater than 0.

<renderer id="naturalNumber" extends="lowerBoundedNumber">
    <renderer-property name="args" value="1"/>
</renderer>
nonNegativeInteger

A renderer for form properties of type java.lang.Integer. It checks if a field value is a whole number greater than or equal to 0.

<renderer id="nonNegativeInteger" extends="lowerBoundedNumber">
    <renderer-property name="args" value="0"/>
</renderer>
integerList

A renderer for multi-valued form properties of type java.lang.Integer[]. It checks if the field values are whole numbers.

<renderer id="integerList" type="java.lang.Integer[]"
 	className="com.siemens.webMgr.taglib.view.
 	                       renderers.StringListRenderer"
	defURL="/WEB-INF/snippets/textField/roStringList.htm"
	altURL="/WEB-INF/snippets/stringList/rwStringList.htm">
    <renderer-property name="hint" value="application.addValueHint"/>
    <renderer-property name="itemRenderer" value="integer"/>
</renderer>

Sample Custom Renderers

customEmployeeNumber

A renderer for form properties of type java.lang.String. It checks if a field value is a valid employee number, using the customEmployeeNumber validator.

<renderer id="customEmployeeNumber" extends="formattedText">
    <renderer-property name="validator" value="customEmployeeNumber"/>
</renderer>
customEmployeeNumberList

A renderer for multi-valued form properties of type java.lang.String[]. It checks if the field values are valid employee numbers.

<renderer id="customEmployeeNumberList" extends="stringList">
    <renderer-property name="itemRenderer"
                       value="customEmployeeNumber"/>
</renderer>
customUid

A renderer for form properties of type java.lang.String. It checks if a field value is a valid unique id of maximum length 8, using the customUid validator.

<renderer id="customUid" extends="formattedText">
    <renderer-property name="validator" value="customUid"/>
    <renderer-property name="args"      value="8"/>
</renderer>
customPhone

A renderer for form properties of type java.lang.String. It checks for phone numbers with area codes 1, 41, 43 and 49, using the customPhone validator.

<renderer id="customPhone" extends="formattedText">
    <renderer-property name="validator" value="customPhone"/>
    <renderer-property name="args"      value="['1','41','43','49']"/>
</renderer>
customPhoneList

A renderer for multi-valued form properties of type java.lang.String[]. It checks if the field values are valid phone numbers.

<renderer id="customPhoneList" extends="stringList">
    <renderer-property name="itemRenderer" value="customPhone"/>
</renderer>
customAge

A renderer for form properties of type java.lang.Integer. It checks if a field value is a whole number greater than or equal to 0 but less than or equal to 120.

<renderer id="customAge" extends="boundedNumber">
    <renderer-property name="args" value="0,120"/>
</renderer>
customPrime

A renderer for form properties of type java.lang.Integer. It checks if a field value is a prime number less than or equal to 10000.

<renderer id="customPrime" extends="integer">
    <renderer-property name="validator" value="customPrime"/>
    <renderer-property name="args"      value="10000"/>
</renderer>
customPrimeList

A renderer for multi-valued form properties of type java.lang.Integer[]. It checks if each field value is a prime number less than or equal to 10000.

<renderer id="customPrimeList" extends="integerList">
    <renderer-property name="itemRenderer" value="customPrime"/>
</renderer>
custom21stCentury

A renderer for form properties of type java.util.Date. It checks if a date lies within the 21st century.

<renderer id="custom21stCentury" extends="boundedDate">
    <renderer-property name="args" value="'20000101','20991231'"/>
</renderer>
customOneYear

A renderer for form properties of type java.util.Date. It checks if a date lies within one year from today.

<renderer id="customOneYear" extends="boundedDate">
    <renderer-property name="args" value="'TODAY','TODAY+365'"/>
</renderer>

Multiple-Property Renderers

Multi-valued properties have array types like java.lang.String[] or java.lang.Integer[].

To obtain a validation renderer for a multi-valued property, extend a suitable predefined non-validating renderer for the type of the property and assign a suitable validation renderer as item renderer. Note that it is not possible to pass individual arguments to the item renderer.

General Renderer Properties

ids

The names of the form properties to be checked by the renderer. A comma-separated list. Samples are

  • dxrStartDate,dxrDisableStartDate,dxrDisableEndDate,dxrEnddate

  • dxrMinPwdLength,dxrMaxPwdLength

tooltips

The tooltips to be displayed for the form properties. You may define a single tooltip for all properties, or indiviual tooltips per property, and even skip tooltips for some properties. Note that the tooltips are appended to any other tooltip defined for a property. Specify a tooltip with its message id relative to “messages.custom.texts.tooltip.format” or “messages.texts.tooltip.format” resp.

Samples are:

  • “all” – The same tooltip for all properties.

  • “first,secondAndHigher” – The first tooltip applies to the first property, the second to any subsequent property.

  • “,,thirdAndHigher” – The same tooltip for the third and any subsequent property, but none for the first two properties.

  • “first,,third,” – Tooltips for the first and third property, no tooltip for the other ones.

Nth property refers to the nth property listed in the above ids.

Base Renderers

minMax

The renderer applies to a list of form properties of type java.lang. Integer. It checks if the values of the number properties are in ascending order (< or <=) and lie within a given range.

<renderer id="minMax" extends="integer"
          altURL="/WEB-INF/snippets/textField/formattedTextFields.htm">
 	<renderer-property name="ids"        value=""/>
	<renderer-property name="mValidator" value="minMax"/>
	<renderer-property name="mArgs"      value=""/>
       <renderer-property name="tooltips"   value=""/>
</renderer>

Renderer properties:

  • ids – The integer property names.

  • mValidator – The validator name.

  • mArgs – Arguments for the minMax validator; optional. Samples are:

    • 0 – Minimum 0, no maximum, <=.

    • 1,1000 – Minimum 0, maximum 1000, <=.

    • false,100,true – No minimum, maximum 100, <.

    • 10,false,true – Minimum 10, no maximum, <.

  • tooltips – The tooltips for the properties.

  • If the renderer is applied to a form which misses some of the listed properties, the missing properties are ignored.
boundedMinMax

The renderer extends minMax by defining an appropriate tooltip for <= checks with minimum and maximum.

<renderer id="boundedMinMax" extends="minMax">
 	<renderer-property name="tooltips" value="boundedMinMax"/>
</renderer>
boundedMinMaxLess

The renderer extends minMax by defining an appropriate tooltip for < checks with minimum and maximum.

<renderer id="boundedMinMaxLess" extends="minMax">
 	<renderer-property name="tooltips" value="boundedMinMaxLess"/>
</renderer>
lowerBoundedMinMax

The renderer extends minMax by defining an appropriate tooltip for <= checks with minimum but without maximum.

<renderer id="lowerBoundedMinMax" extends="minMax">
 	<renderer-property name="tooltips" value="lowerBoundedMinMax"/>
</renderer>
lowerBoundedMinMaxLess

The renderer extends minMax by defining an appropriate tooltip for < checks with minimum but without maximum.

<renderer id="lowerBoundedMinMaxLess" extends="minMax">
 	<renderer-property name="tooltips"
                          value="lowerBoundedMinMaxLess"/>
</renderer>
checkedDate

The renderer applies to a list of form properties of type java.util.Date without time components. It checks if the values of a list of date properties are in ascending order (< or <=).

The renderer is defined as follows:

<renderer id="checkedDate" extends="calendar"
          altURL="/WEB-INF/snippets/calendar/checkedDate.htm">
    <renderer-property name="ids"        value=""/>
    <renderer-property name="mValidator" value="dates"/>
    <renderer-property name="mArgs"      value=""/>
    <renderer-property name="tooltips"   value=""/>
</renderer>

Renderer properties:

  • ids – The date property names.

  • mValidator – The validator name.

  • mArgs – Arguments for the dates validator; optional. Samples are:

    • true – Use <.

    • false – Use <= (default).

  • tooltips – The tooltips for the properties.

  • If the renderer is applied to a form which misses some of the listed properties, the missing properties are ignored.
checkedTime

The renderer applies to a list of form properties of type java.util.Date with time components. It checks whether the values of a list of date properties are in ascending order (< or <=).

The renderer is defined as follows:

<renderer id="checkedTime" extends="time"
          altURL="/WEB-INF/snippets/time/checkedTime.htm">
    <renderer-property name="ids"        value=""/>
    <renderer-property name="mValidator" value="times"/>
    <renderer-property name="mArgs"      value=""/>
    <renderer-property name="tooltips"   value=""/>
</renderer>

Renderer properties:

  • ids – The date property names.

  • mValidator – The validator name.

  • mArgs – Arguments for the times validator; optional. Samples are:

    • true – Use <.

    • false – Use <= (default).

  • tooltips – The tooltips for the properties.

  • If the renderer is applied to a form which misses some of the listed properties, the missing properties are ignored.

  • There’s a corresponding renderer checkedTimeWithSeconds for times including seconds.

Predefined Renderers

startEndDate

The renderer checks if the values of properties dxrStartDate and dxrEndDate are consistent, ie

dxrStartDate <= dxrEndDate

The renderer is defined as follows:

<renderer id="startEndDate" extends="checkDate">
    <renderer-property name="ids"  value="dxrStartDate,dxrEndDate"/>
    <renderer-property name="tooltips" value="startEndDate"/>
</renderer>
startEndDateLess

The renderer checks if the values of properties dxrStartDate and dxrEndDate are consistent, ie

dxrStartDate < dxrEndDate

The renderer is defined as follows:

<renderer id="startEndDateLess" extends="checkDate">
    <renderer-property name="ids"   value="dxrStartDate,dxrEndDate"/>
    <renderer-property name="mArgs" value="true"/>
    <renderer-property name="tooltips" value="startEndDateLess"/>
</renderer>
startEndDateWithDisabled

The renderer checks if the values of properties dxrStartDate, dxrEndDate, dxrDisableStartDate and dxrDisableEndDate are consistent, ie

dxrStartDate <= dxrDisableStartDate <= dxrDisableEndDate <= dxrEndDate

If a form does not include disable dates, the check reduces to

dxrStartDate <= dxrEndDate.

The renderer is defined as follows:

<renderer id="startEndDateWithDisabled" extends="checkdDate">
    <renderer-property name="ids"
              value="dxrStartDate,dxrDisableStartDate,
                                  dxrDisableEndDate,dxrEndDate"/>
    <renderer-property name="tooltips"
              value="startEndDateWithDisabled"/>
</renderer>
startEndDateWithDisabledLess

The renderer checks if the values of properties dxrStartDate, dxrEndDate, dxrDisableStartDate and dxrDisableEndDate are consistent, ie

dxrStartDate < dxrDisableStartDate < dxrDisableEndDate < dxrEndDate

If a form does not include disable dates, the check reduces to

dxrStartDate < dxrEndDate

The renderer is defined as follows:

<renderer id="startEndDateWithDisabledLess" extends="checkedDate">
    <renderer-property name="ids"
              value="dxrStartDate,dxrDisableStartDate,
                                  dxrDisableEndDate,dxrEndDate"/>
    <renderer-property name="mArgs" value="true"/>
    <renderer-property name="tooltips"
              value="startEndDateWithDisabledLess"/>
</renderer>

Sample Custom Renderers

customPasswordLength

The renderer checks if the required minimum password length is less than or equal to its maximum length. The minimum length must not be less than 1. Maximum value 0 means unbounded (since its less than the minimum).

<renderer id="customPasswordLength" extends="minMax">
    <renderer-property name="ids"
                       value="dxrPwdMinLength,dxrPwdMaxLength"/>
    <renderer-property name="mArgs" value="1,0"/>
</renderer>
customDepartureArrival

The renderer checks if departure date and arrival date are in proper order.

<renderer id="customDepartureArrival" extends="checkedDate">
    <renderer-property name="ids" value="departureDate,arrivalDate"/>
    <renderer-property name="tooltips" value="customDepartureArrival"/>
</renderer>
customEmployee

The renderer cross-checks employee type and employee number. It checks for 5-digits employee numbers. There’s no tooltip for employee type, while the tooltip for employee number is “customEmployee”.

<renderer id="customEmployee" extends="text"
	   altURL="/WEB-INF/snippets/textField/formattedTextFields.htm">
 	<renderer-property name="ids"
 	                   value="employeeType,employeeNumber"/>
	<renderer-property name="mValidator" value="customEmployee"/>
 	<renderer-property name="mArgs"      value="5"/>
 	<renderer-property name="tooltips"   value=",customEmployee"/>
	<renderer-property name="validator"  value=""/>
 	<renderer-property name="args"       value=""/>
</renderer>
T0 he renderer assigns empty values to properties “validator” and “args” to avoid Javascript errors caused by the expressions “${validator.jsd}” and “${args}” used in snippet formattedTextFields.htm.
customStartEndTime

The renderer checks whether a start time truly precedes the end time. It defines the names of the affected properties, the tooltip to be displayed for both properties, and that the start time must not be equal to the end time (by setting the single argument to “true”.)

<renderer id="customStartEndTime" extends="checkTime">
    <renderer-property name="ids"      value="startTime,endTime"/>
    <renderer-property name="mArgs"    value="true"/>
    <renderer-property name="tooltips" value="customStartEndTime"/>
</renderer>

Assigning Renderers to Properties

This section gives some samples for how to assign renderers to form properties.You can assign a renderer to an individual form property in a form bean definition.On the other hand, you can define a renderer as default renderer for specific properties.

Assigning Renderers to Individual Form Fields

In form beans, you can assign the renderer to individual form fields, thereby overriding the default renderers.

Note that you cannot assign individual renderers to properties dynamically inserted into forms to perform request workflow tasks.

Note that validation renderers do not work with editable table cells (data properties).Do not assign validation renderers to data properties.

Single-Property Renderers

<!— Fax number with predefined renderer -->
<form-property name="facsimileTelephoneNumber" type="java.lang.String"
               width="100%" y="+1"
               fieldRenderer="fax"/>
<!— Employee number with custom renderer -->
<form-property name="employeeNumber" type="java.lang.String"
               width="100%" y="+1"
               fieldRenderer="customEmployeeNumber"/>
<!— UID property with default maximum length 8 -->
<form-property name="uid" type="java.lang.String"
               width="100%" y="+1" mandatory="true"
               fieldRenderer="customUid"/>
<!— UID property with individual maximum length 10 -->
<form-property name="uid" type="java.lang.String"
               width="100%" y="+1"
               fieldRenderer="customUid"
               rendererProperties="args:10"/>
<!— Phone number property with default country codes -->
<form-property name="telephoneNumber" type="java.lang.String"
               width="100%" y="+1"
               fieldRenderer="customPhone"/>

<!— Phone number property with individual country codes -->
<form-property name="telephoneNumber" type="java.lang.String"
               width="100%" y="+1"
               fieldRenderer="customPhone"
               rendererProperties="args:['30','31','33','39']"/>
<!— Mail addresses with predefined renderer -->
<form-property name="mail" type="java.lang.String[]"
               spanX="4" spanY="3" height="65" width="100%" x="1"
               fieldRenderer="mailList"/>
<!— Phone numbers with custom renderer -->
<form-property name="telephoneNumber" type="java.lang.String[]"
               spanX="4" spanY="3" height="65" width="100%" y="+1"
               fieldRenderer="customPhoneList"/>
<!— Maximum password age with predefined renderer -->
<form-property name="dxrPwdMaxAge" type="java.lang.Integer"
               label="dxrpwdmaxage" width="50" y="+1"
               fieldRenderer="nonNegativeInteger"/>
<!— Minimum password length with predefined renderer -->
<form-property name="dxrPwdMinLength" type="java.lang.Integer"
               label="dxrpwdminlength" width="50" y="+1"
               fieldRenderer="naturalNumber"/>
<!— Two equivalent definitions: -->
<!— Age property with custom renderer -->
<!— Age property with predefined renderer and individual args -->
<form-property name="age" type="java.lang.Integer"
               width="50" y="+1"
               fieldRenderer="customAge"/>
<form-property name="age" type="java.lang.Integer"
               width="50" y="+1"
               fieldRenderer="integer"
               rendererProperties="args:0,120"/>
<!— Number list with custom renderer -->
<form-property name="primes" type="java.lang.Integer[]"
               height="65" width="200" y="+1"
               fieldRenderer="customPrimeList"/>

Multiple-Property Renderers

<!— Two equivalent definitions: -->
<!— Minimum/maximum password length with custom renderer -->
<!— Minimum/maximum password length with predefined renderer and individual ids -->
<!— Checks for 1 <= dxrPwdMinLength <= dxrPwdMaxLength -->
<form-property name="dxrPwdMaxLength" type="java.lang.Integer"
               label="dxrpwdmaxlength" width="50"
               fieldRenderer="customPasswordLength"/>
<form-property name="dxrPwdMaxLength" type="java.lang.Integer"
               label="dxrpwdmaxlength" width="50"
               fieldRenderer="minMax"
               rendererProperties=
                    "ids:dxrPwdMinLength,dxrPwdMaxLength;mArgs:1,0"/>
<!— Date properties with predefined renderer -->
<form-property name="dxrDisableEndDate" type="java.util.Date"
               width="100" x="1"
               fieldRenderer="checkedDate"/>
<!— Departure/arrival dates with custom renderer -->
<form-property name="arrivalDate" type="java.util.Date"
               width="100" y="+1"
               fieldRenderer="customDepartureArrival"/>
<!— First/second/third dates with predefined renderer and individual ids -->
<form-property name="third" type="java.util.Date"
               width="100" x="2"
               fieldRenderer="checkedDate"
               rendererProperties="ids:first,second,third"/>

Combining Single-Property and Multiple-Property Renderers

The next sample combines the single-property renderer boundedDate with the multiple-property renderer startEndDateLess. The single-property validator checks if the dates lie within the 21st century. The multiple-property validator makes sure that the start date precedes the end date.

<form-property name="dxrStartDate" type="java.util.Date"
               width="100" y="+1"
               fieldRenderer="boundedDate"
               rendererProperties="args:'20000101','20991231'"/>
<form-property name="dxrEndDate" type="java.util.Date"
               width="100" x="1"
               fieldRenderer="startEndDateLess"
               rendererProperties="args:'20000101','20991231';
                                   tooltip:boundedDate"/>

For both fields, the tooltip is the concatenation of the “boundedDate” tooltip with the “startEndDateLess” tooltip.

Assigning Validation Renderers as Default Renderers

Default renderers apply to static form properties defined in forms-config.xml files, as well as to dynamically generated properties of forms used to perform request workflow tasks.

File: WEB-INF/config/defaultRenderer.properties

# Predefined renderers
dxrdisableenddate        = startEndDateWithDisabled
dxrenddate               = startEndDateWithDisabled
facsimiletelephonenumber = fax
mail                     = mailList
mobile                   = phone
telephonenumber          = phone

# Custom renderers
age                      = customAge
arrivaldate              = customDepartureArrival
dxrpwdmaxlength          = customPasswordLength
telephonenumber@dxruser  = customPhone
uid                      = customUid

Customization Hints

See the chapter on “Customization Files” for details.

Javascript Code

Add custom validators and the calls to register them to a custom Javascript file like resources/custom/scripts/custom.js.

Add an include instruction for the file to the custom ScriptsAndStyles-JSP:

<script src="resources/custom/scripts/custom.js"></script>

Tooltips

Add custom tooltips to the object messages.custom.texts in your custom message files like resources/custom/scripts/messages/<language>/messages.js.

Add an include instruction for the file to the custom ScriptsAndStyles-JSP:

<script src="resources/custom/messages/
        <c:out value="${sessionScope['com.siemens.webMgr.language']}"/>
                      /messages.js">
</script>

Renderers

Add custom renderers to a custom renderers configuation file like WEB-INF/custom/config/renderers-config.xml.

Validator Samples

This section shows the implementation of some sample validators.

The validator employeeNumber checks:

  • If an employee number matches a given regular expression.

The validator phone checks:

  • If a phone number matches a given regular expression.

  • If its country code is contained in a list of predefined country codes.

The validator uid checks:

  • If a user id matches a given regular expression.

  • If it does not exceed a given maximum length.

The validator employee checks a combination of employee number and employee type:

  • Whether the employee number is a sequence of digits of a given length (if not empty).

  • Whether the employee number is specified in case the field is mandatory.

  • Whether the employee number is specified in case employee type is “Internal”.

Javascript Code

Each validator object defines a regular expression and/or implements a check function.

The registration defines names for the validators to be used by renderers.

resources/custom/scripts/custom.js

var custom = {
    ...
    /* =================== Custom validators =================== */

    /* ---------- Single-property validators ---------- */

    employeeNumber: {
        expr: /^\d\d-[A-Z][A-Z]$/
    },

    phone: {
        check: function(value,countryCodes) {
            if (!value)
                return true;
            var m = value.match(/^[+](\d+) \d+ \d+$/);
            if (m) {
                if (!countryCodes || countryCodes.length === 0)
                    return true;
                for (var i = 0; i < countryCodes.length; i++)
                    if (m[1] === countryCodes[i])
                        return true;
            }
            return false;
        }
    },

    uid: {
        expr: /^[\dA-Z]*$/,

        check: function(value,maxLen) {
            if (!maxLen || maxLen <= 0 || !value)
                return true;
            return value.length <= maxLen;
        }
    },

    /* ---------- Multiple-property validators ---------- */

    employee: {
        check: function(nodes,onChange,numDigits) {
            if (nodes.length < 2)
                return null;
            var empType   = nodes[0];
            var empNumber = nodes[1];

            var v = trimSpaces(empNumber.value);
            onChange && (empNumber.value = v);

            var expr = new RegExp("^(?:[0-9]{"+numDigits+"})$");
            var ok   = v ? expr.test(v) : !empNumber.mandatory;

            if (ok && empType.selectedIndex !== -1) {
                if ("Internal" ===
                        empType.options[empType.selectedIndex].value)
                    ok = v.length > 0;
            }

            return ok ? {ok:[1]} : {inv:[1]};
        }
    },
    ...
};

validators.register(
    [ "customEmployee", custom.employee ],
    [ "customEmployeeNumber", custom.employeeNumber ],
    [ "customPhone", custom.phone ],
    [ "customUid", custom.uid ]
);

Tooltips

resources/custom/scripts/messages/en/messages.js

messages.custom = {
    texts: {
        tooltip: {
            format: {
                customEmployee:       "An employee number is ...",
                customEmployeeNumber: "Two digits (0-9), ...",
                customPhone:          "The phone number format ...",
                customUid:            "A unique ID must include ..."
            }
        }
    }
};