String validator

Test a string value to see if it conforms with a set of JSF validation constraints.

The StringValidator is used to test that a value conforms to a set of validation constraints. The validator is passed a JavaScriptâ„¢ string. If a string is a masked string, it should be converted (using the MaskConverter) to a string (stripped of literals) before it is passed to the validator.

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 (the value is neither null or the empty string). 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-length is specified as a constraint, a value's length (if not null) must be greater than or equal to the specified length. If a maximum length is specified as a constraint, the value's length must be less than or equal to the maximum length.

If a regular expression is provided, the value must match the expression at least once. (value.match(exp) != null) must evaluate to true. Either a regular expression or a reference to a pre-built regular expression may be provided.

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:
  1. required
  2. minimum-bound
  3. maximum-bound
  4. constraint
  5. constraint-regexpression
  6. constraint-expression

JavaScript constructor

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

id

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

Attributes

Table 1. String 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-length

The minimum number of characters the string must contain.

maximum-length

The maximum number of characters the string may contain.

constraint-regexpression

A Javaâ„¢ regular expression that the value must match at least once. See the Java documentation for a description of regular expressions.

constraint

Apply a pre-defined regular expression. The following pre-defined expressions are available:
  • AlphabetExOnly means ^[A-Za-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF]+$
  • AlphabetOnly means ^[A-Za-z]+$
  • DigitOnly means ^[0-9]+$
  • AlnumExOnly means ^[A-Za-z0-9\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF]+$
  • AlnumOnly means ^[A-Za-z0-9]+$
  • UpperCaseOnly means ^[A-Z]+$
  • LowerCaseOnly means ^[a-z]+$

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. API calls

API call

Description

boolean = validate(value)

Validate a string. 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.

Example code

Validate the value of an input field.

// Construct a validator that checks that a string looks like an email address
hX.addValidator("1Z", new hX.StringValidator("required:true", "minimum-length:5", 
                  "constraint-regexpression:"^[A-Za-z0-9._%-]+@[A-Za-z0-9._%-]+\.[A-Za-z]{2,4}$"));

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

Feedback