Make your own free website on Tripod.com

NetDynamics' Display Field Formatting and Validation

The NetDynamics Studio allows developers to provide default formatting and validation masks for display field values. These features are at best under-documented, hence you may find the following overview useful.

Studio-generated formatting and validation is available for display fields that extend the spider.visual.CSpFormatField class, namely spider.visual.CSpCommonTextBox and spider.visual.CSpCommonStaticText. The relevant class hierarchy looks like this:

CSpFormatField and its children

Formatting and validation options are accessible in the Studio by right-clicking on the appropriate display field and selecting "Properties...".

Formatting

Five general types of formatting are available:
None

This is the default type. No formatting will be applied.

Date/Time

Both "predefined" and "custom" date/time formatting options are available.

The predefined option allows you to select from one of a number of self-explanatory formats. This is more-or-less equivalent to the spider.session.CSpDatetime.format(int) and spider.session.CSpDatetime.format(int,java.lang.String) methods.

The custom formatting option provides formatting similar to that available with the spider.session.CSpDatetime.format(java.lang.String) and java.text.SimpleDateFormat.format(java.util.Date) methods.

The general strategy is to supply a format mask that is used to render the CSpDatetime value. Most characters pass directly throught to the value to display, but certain "special strings" are used to indicate where in the mask to substitute date/time fields. The following table enumerates these special strings.

Special String Replaced With
d Day of the month in one or two digits, as needed (1 through 31)
dd Day of the month in two digits (01 through 31)
m Month of the year in one or two digits, as needed (1 through 12)
mm Month of the year in two digits (01 through 12)
mmm Abbreviated month (Jan through Dec)
mmmm Full name of the month (January through December)
yy Last two digits of the year (00 through 99)
yyyy Year with century (0000 through 9999)
h Hour in one or two digits, as needed (0 through 23)
hh Hour in two digits (00 through 23)
n Minute in one or two digits, as needed (0 through 59)
nn Minute in two digits (00 through 59)
s Second in one or two digits, as needed (0 through 59)
ss Second in two digits (00 through 59)
l Milliseconds in one, two, or three digits, as needed (0 through 999)
lll Milliseconds in three digits (000 through 999)
AM/PM Uppercase letters AM or PM, as appropriate. (Also forces twelve-hour clock.)
am/pm Lowercase letters am or pm, as appropriate. (Also forces twelve-hour clock.)
A/P Uppercase letter A or P, as appropriate. (Also forces twelve-hour clock.)
a/p Lowercase letter a or p, as appropriate. (Also forces twelve-hour clock.)

Other characters are passed directly into displayed string. Hence the format mask

mmm d, yyyy @ hh:mm:ss AM/PM

would generate a display similar to:

Aug 8, 1998 @ 10:58:32 AM

If you would like use the "special strings" in the format mask, you may use a backslash ("\") as an escape character. For example, the format mask

T\he ti\me is hh:mm:ss AM/PM o\n mmm d, yyyy.

would generate a display similar to:

The time is 10:58:32 AM on Aug 8, 1998.

If you would like additional formatting options, such as a time-zone identfier, you must perform the formatting manually.

Note that using the custom format mask is slightly slower than using one of the predefined values.

For more information, see the javadoc pages for spider.session.CSpDatetime, java.util.Date, java.util.Calendar and java.text.DateFormat.

Currency

The currency formatting type formats the display field's value as a number with an optional and variable currency symbol, optional and variable thousands separator character, a variable decimal point, and a variable number of decimal places. Also, you may provide special formatting for negative values. The dialog box is fairly self-explainatory.

Custom currency formatting may be performed in the Java code. Relevant classes include java.text.NumberFormat and java.text.DecimalFormat.

Number

The number formatting type formats the display field's value as a number with a variable thousands separator character, a variable decimal point, and a variable number of decimal places. Also, you may provide special formatting for negative values. The dialog box is fairly self-explainatory.

Custom number formatting may be performed in the Java code. Relevant classes include java.text.NumberFormat and java.text.DecimalFormat.

Alphanumeric

Alphanumeric formatting allows one to specify a format mask, as in the Date/Time type. The following table summarizes the available "special characters".

Special Character Replaced With
A The corresponding alphabetic character (including punctuation, namely [^0-9])
# The corresponding numeric character (namely [0-9])
* Any corresponding character.

Other characters are passed directly into displayed string. If you would like use the "special characters" in the format string, you may use a backslash ("\") as an escape character.

Here are some examples:

Value Format Mask Rendered Value
123456789 ###-##-#### 123-45-6789
My SS# is 123 45 6789 . ###-##-#### 123-45-6789
1-23-45-67-89 ###-##-#### 123-45-6789
C9 0x** 0xC9
C9 0xAA C9
throws CSpFormatException
C9 0x## C9
throws CSpFormatException
C9 0xA# 0xC9
C9 0x#A C9
throws CSpFormatException
9C9 0x#A 0x9C

Note that the Studio formatting properties do not effect a display field's value (as accessed by getDisplayFieldValue or getValue). The formatting is applied only when the HTML text for the display field is being generated. Hence the first method at which you can safely access the formatted text is during the spider.event.CSpHtmlOutputEvent (of type ON_BEFORE_HTML_OUTPUT_EVENT) for HTML objects, or during the java.awt.event.TextEvent (of type TEXT_VALUE_CHANGED) for Java objects, which is published by the Java object's "AWT peer". (Note that this TextEvent is triggered every time the text value is changed, not just on the first display.) Similiarly, the formatted value is only available via the spider.visual.CSpDisplayField.getHtmlText, spider.visual.javapeer.ISpJavaTextComponentPeer.getText and spider.visual.javapeer.ISpJavaLabelPeer.getText methods.

More information about ND's formatting can be found in the javadoc documentation for the spider.visual.CSpFormatField and spider.visual.CSpFormatter classes. The java.text package provides some useful classes if you want to implement your own formatting utilities.