Format definition

Description

Only available if Client side formatting is checked. Specify the client side format.

Discussion

Displays the format builder to create the client side format definition. Depending on the Format type, you will either be presented the Number Format Builder or Custom Client Side Format Builder, both shown below.

images/formatDefinition.png

Mask Format

Available for Character, Date, Date-Time, and Shortime field types.

The Mask builder can be used to create a Simple or Conditional mask to format the characters when data is entered in the field. If a dynamic mask is desired, a JavaScript function can be used to create the mask when the control receives focus.

images/maskBuilder.png
The Mask Builder

The mask definition can contain the following placeholders:

Placeholder
Description
L

Allows characters A-Z (upper case only)

l

Allows characters A-Z, a-z (upper and lower case)

#

0-9 , decimal or negative sign

N

Allows A-Z (upper case only), 0-9, decimal or negative sign

n

Allows A-Z, a-z (upper and lower case), 0-9, decimal or negative sign

A

A-Z (upper case only), 0-9

a

A-Z, a-z (upper and lower case), 0-9

0

0-9

&

any character

All other characters not listed will be printed verbatim as part of the mask. To include a special placeholder in the mask, escape the character using the '\' character. For example, the following prints the character "A" at the end of the mask that contains 3 digits (0-9):

000\A

In addition to creating defining the mask, several pre-defined masks are available. Use the Insert pre-defined mask link below the Mask field to insert one of the following masks:

Pre-Defined Mask
Mask Format
US Phone Number

(000) 000-0000

Social Security Number

000-00-0000

Zip code - 5 digit

00000

Zip code - 9 digit

00000-0000

Postal Code - Canada

L0L 0L0

Creating a Conditional Mask

The mask can be computed dynamically at run-time by specifying a Conditional mask and specifying the name of a JavaScript function that computes the mask. The JavaScript function is called when the control receives focus. The JavaScript function must return the mask as a string. The string can use the format placeholders defined above for specifying the mask. For example:

function getPhoneNumberMask(e) {
    var country = {dialog.object}.getValue('COUNTRY');
    if(country=='USA') {
        return '(000) 000-0000';
    } else if(country=='UK') {
        return '00-000-000-0000';
    } else {
        return '00000000000000';
    }
}

Number Format

Available for Numeric fields only.

The Number Format Builder can be used to create a numeric mask for the control's value.

images/numberFormatBuilder.png
The Number Format Builder dialog.

Number Format Properties

Number can be blank

Specify if a blank number is allowed

Blank value

The value in the field that is considered to be 'zero'. This value is typically '0'. If you wish to display the value '0' in the field, use the special value '-99999'.

Has maximum value

Specify if there is a maximum value allowed for the field

Maximum value

The maximum value allowed.

Has minimum value

Specify if there is a minimum value allowed for the field

Minimum value

The minimum value allowed.

Round value

Specify whether or not the value should be rounded.

Round precision

Specify the number of decimal places to which the value should be rounded.

Round direction

Specify the rounding direction.

Option
Description
Default

Rounds up for values with decimal part that is equal to or above 0.5 of the round precision. Rounds down for values with decimal part less than 0.5 of the round precision.

Up

Always round the value up.

Down

Always round the value down.

Decimal character

Specify the decimal character. IMPORTANT: If you select a decimal that is not a period, you must specify the Display format property for this field.

Has thousands separator

Specify if thousands are separated into groups

Thousands separator

Specify the thousands separator character

Has special format for negative numbers

Specify if negative numbers are specially formatted.

Negative number format

Negative number format Choices include.

Prefix

Specify the prefix character(s). This is often a currency symbol. For unicode characters use Javascript notation, but replace '\u' with '{unicode}' e.g. {unicode}20A6.

Suffix

Specify the suffix character(s). This is often a currency symbol.

Has fill character

Specify if empty space in the input control is filled with a special character. The size of the field is defined by the control's 'MaxLength' property. If this property is not defined then the field will not be filled.

Fill character

Specify the fill character.

Custom Format

Available for all field types.

A Custom format can be specified for any field type. The Custom format uses JavaScript to format the value entered by the user. The JavaScript can be entered directly into the Parse Out text area. An optional JavaScript function can be defined that pre-processes the value entered by the user before passing it to the Parse Out script.

images/customFormatBuilder.png
The Custom Client Side Format Builder dialog.

Parse Out Examples:

// Convert to uppercase
data = data.toUpperCase()

// convert data to a number
data = $u.s.toNum(data)