DateTime validator

Test a string value (formatted as a JSF date/time value) or a JavaScriptâ„¢ date object to see if it conforms with a set of JSF validation constraints.

The DateTimeValidator is used to test that a value conforms to a set of validation constraints. The validator can be passed a JavaScript date object or it can be passed a string which is converted to a date object using the supplied DateTimeConverter (if the conversion fails, the value is invalid).

Validation constraints are supplied when the validator is constructed (or they can be added/removed using the Get/SetAttribute calls). Any number of constraints may be supplied. Supplying no constraints is not meaningful.

If the required constraint is supplied (and set to true), the validator requires that the value be non-null (if a date object is provided) or a non-empty string (if a string is supplied). If required is not set, null/empty string are considered valid values regardless of any other constraints (that is "null" is always a valid value if required is not set).

If a minimum-bound is specified as a constraint, a value (if not null) must be greater than or equal to the specified bound. If a maximum bound is specified as a constraint, the value must be less than or equal to the maximum bound.

A JavaScript EL expression can be used to test that a value is within a set, to test if a value is in a discontinuous range, and so on. Currently it can not be used to compare one value with another value on the page.

Although it doesn't affect the result of validation, constraints are tested in the following order:
  • required
  • minimum-bound
  • maximum-bound
  • constraint-expression

JavaScript constructor

hX_5.addValidator("id", new hX_5.DateTimeValidator(attributes)); where

id

The ID of the HTML tag to which the component is attached.

Attributes

Table 1. Date time validator attributes

Attribute name

Description

required

If required, the value may not be null or the empty string. If not required, the value may be null or the empty string and the other validation constraints are skipped.

minimum-bound

The minimum allowed value. The bounds should be formatted as yyyyMMddHHmmssSSS where trailing components may be omitted.

maximum-bound

The maximum allowed value. The bounds should be formatted as yyyyMMddHHmmssSSS where trailing components may be omitted.

constraint-expression

A JavaScript EL expression that must be satisfied. A JavaScript EL expression is the same as a JSF EL expression with the following exceptions:
  • Operators may not be expressed using the "string" form of the operator (for example, use == not .eq.)
  • The only value that can be referenced is @testValue which represents the value being tested.
  • Date/time components within @testValue can be accessed using the Javaâ„¢ accessors. Specifically, .date, .day, .hours, .minutes, .month, .seconds, .timezoneOffset, .time and .year may be used.

API calls

Table 2. Date time validator API calls

API call

Description

boolean = validate(value, converter)

Validate a value (either a string or a date object). Requires either a converter object or the ID of a converter. Returns true if value passes. Returns false if value fails and lastError is set.

string = lastError()

If a conversion fails, returns the reason for the failure as a localized string.

object = setAttribute(attribute)

Sets an attribute or changes its value (if it was set previously).

string = getAttribute(attribute-name)

Retrieves the current value of an attribute.

Limitations

As with the DateTime converter, the effective range of dates that can be validated are October 15, 1582 through December 31, 9999.

Example code

Validate the value of an input field.

// Construct a converter with a pattern of MMMM dd, yyyy
hX.addConverter("AZ", new hX.DateTimeConverter("format:MMMM dd, yyyy", "strict:2", 
                  "base-2digit-span:30"));

// Construct a validator that checks that a field is present and the date is the 1st or the 15th of the month
hX.addValidator("1Z", new hX.DateTimeValidator("required:true", 
                  "constraint-expression:(@testValue.day == 1 || @testValue.day == 15"));

// Validate a value
var x = document.getElementById("form1:textA");
var v = hX.getValidatorById("1Z");
if (!v.validate(x.value, "AZ")) alert ("ERROR: " + v.lastError());

Feedback