Validating a Postal Code

There are several interesting scripting validation techniques that can be demonstrated in the context of a Canadian postal code field.  While the subject domain is fairly specific, the techniques used are applicable to other field validations. The challenge is to get an accurate and user-friendly data capture experience for a postal code. Some of the considerations:

• Make sure the field value conforms to the rules for Canadian postal codes (use regular expressions for validating)
• Make sure that error messages are as specific as possible to assist better user input (customize validation error messages)
• Make sure the user can optionally key in a space inside their postal code  (use an edit picture clause)
• Make sure the postal code is entered in upper case (modify keystrokes on the change event)
• Make sure the postal code value is consistent with other address fields: province and city (inter-field validation)

The sample form can be found here.

Canadian Postal Code Rules

The default way to validate a postal code is to use a validation picture clause: text{A9A 9A9}. However, this picture allows many illegal postal codes. For example, the meta character “A” in a picture clause allows any Unicode letter value – whereas a postal code letter is far more restricted:

• The first character of a Canadian postal code corresponds to a geographic region and is limited to the set of characters: ABCEGHJKLMNPRSTVXY
• The third and fifth characters may not include the letters D, F, I, O, Q or U (because they are hard for OCR software to deal with).

In order to implement these restrictions, we can use regular expressions. The JavaScript string class has a match() method that searches for a pattern.  For example, the code to validate the first character is:

if (vTestValue.charAt(0).match(/[ABCEGHJKLMNPRSTVXY]/) == null) { … error condition … }

Specific Error Messages

When the user enters an invalid postal code, be as specific as possible in telling them what to fix. There is a world of difference between: “Invalid postal code” and “Second, fourth and sixth postal characters must be numeric” For the person who typed in a letter “O” instead of a “0″ (zero), this will be the clue they need to correct their error. To make this work, validate the portions of the postal code individually and then set the field error message accordingly:

var vNums = vTestValue.charAt(1) +
vTestValue.charAt(3) +
vTestValue.charAt(5);
if (vNums.match(/[0-9][0-9][0-9]/) == null)
{
vTestField.validationMessage =
“Second, fourth and sixth postal characters must be numeric”;
return false;
}

Note that you might choose to store error messages as form variables.  That way they will be examined by Designer’s spell checker.

The Optional Space

The user ought to be able to enter their data with or without a space – but we want to store it consistently – without the space. To accomplish this, use an edit picture clause: text{OOO OOO} Edit picture clauses are used by Reader to:

1. format the raw value for editing when the user enters the field
2. parse the edited value to set the raw value when the user exits the field

For example, a raw value: A2A2A2 will be displayed as A2A 2A2 when the user enters the field. When they exit the field, both A2A2A2 and A2A 2A2 will parse into A2A2A2 successfully. Note that I used the meta character “O” (letter or digit). This is so that if the user enters invalid characters, we still parse/format the space correctly. Naturally, we also use a display picture clause to render with the space: text{A9A 9A9}

Upper Case Only

The easiest way to force the value to upper case is to trap the characters as the user enters them and convert them as they type. We do this with a very simple change event:

form1.address.PostalCode::change – (JavaScript, client) // Change all user entered characters to upper case. xfa.event.change = xfa.event.change.toUpperCase();

Because we know that the input data is in upper case, it makes our validation logic cleaner, as it needs only be concerned with the upper case variations.

Consistency with City and Province

The first character of the postal code determines the geographic region.  We can assign the province based on the postal code. In a couple of cases (M and H) we can also assign the value for the city (Toronto and Montréal).

More Considerations

While we now have a better-than-average postal code validation, it does not ensure100% correctness. Since only about 12% of the possible 7.2 million postal code variations are currently allocated, it is still pretty easy to enter a non-existent postal code. Because this validation script is as specific as possible, it does mean that the script may need to be updated as the postal code rules evolve (The Canadian postal code rules were modified after Nunavut was added in 1999). My sources for postal code specifics were: http://en.wikipedia.org/wiki/Canadian_postal_code and http://www.columbia.edu/kermit/postal-ca.html.