Value Formatting Syntax
The syntax for Value Formatting is:
([prefix character/s]field[suffix character/s][{field-option1,field-option2,...}])+
| where | prefix character/s and suffix character/s are optional specifiers used to control alignment and the display of positive/negative symbols; |
| field can be any datatype-specific formatting or text; and |
| {field-option(s)} is an optional qualifier, that enables additional formatting options. |
Explanation of definition syntax
The Value Formatting definition is constructed as follows:
•The definition is composed of one or more fields. For example, the definition DD Month YYYY has three fields.
•Fields can be run together, or they can be separated by the following characters: space, hyphen, comma, colon, period, or by a text string in single or double quotes. For example, in the definition: DD-Month' in the year 'YYYY, the fields DD and Month are separated by a hyphen, and the fields Month and YYYY are separated by a text string enclosed in single quotes.
•A field can have optional prefix and/or suffix character/s. For example: <+###,##0.00.
•A field can have one or more optional field-options. The field-option/s for each field must be contained in a single set of curly braces, and must follow the field without any intervening space. Multiple field-options for a single field are separated by "," (comma). For example, in the definition: DD Month{uc,ro} YYYY, the curly-brace-enclosed uc and ro are field-options for the field Month.
Examples
Example of Value Formatting for an xs:decimal datatype:
"$"(##0.00)
Examples of the output would be:
$ 25.00
$ 25.42
$267.56
Example of Value Formatting for an xs:date datatype:
DD Month{uc,ro} YYYY
| where | uc and ro are field-options for making the Month field uppercase and read-only, respectively |
An example of the output would be:
24 SEPTEMBER 2003
Field types
A field type represents a component of the data and the way that component is to be formatted. The formatting inherent in the field type can be modified further by prefix and suffix modifiers as well as by field options. The following tables list the available field types. Note that, in the drop-down menu of the Value Formatting dialog, there are type-specific and field-only Value Formatting definitions. You can select one of these and modify them as required by adding prefix modifiers, suffix modifiers, and/or field options.
Field Type | Explanation |
# | Space if no digit at position |
0 | Zero if no digit at position |
. | Decimal mark |
, | Digit group separator |
Y | Year |
y | year (base = 1930); see Note below |
MM | Month, must have length of 2 |
DD | Day, must have length of 2 |
W | Week number |
d | Weekday number (1 to 7) |
i | Day in the year (1 to 366) |
hh | Hour (0 to 23), must have length of 2 |
HH | Hour (1 to 12), must have length of 2 |
mm | Minute, must have length of 2 |
ss | Second, must have length of 2 |
AM | AM or PM |
am | am or pm |
AD | AD or BC |
ad | ad or bc |
CE | CE or BCE |
ce | ce or bce |
Field Type | Explanation |
Weekday | Weekday (Sunday, Monday...) |
WEEKDAY | Weekday (SUNDAY, MONDAY...) |
weekday | Weekday (sunday, monday...) |
Wkd | Weekday (Sun, Mon...) |
WKD | Weekday (SUN, MON...) |
wkd | Weekday (sun, mon...) |
Month | Month (January, February...) |
MONTH | Month (JANUARY, FEBRUARY...) |
month | Month (january, february...) |
Mon | Month (Jan, Feb...) |
MON | Month (JAN, FEB...) |
mon | Month (jan, feb...) |
Notes on field length and entry length
The following points relating to the length of data components should be noted:
Length of date fields: When fields such as MM, DD, HH, hh, mm, and ss are used, they must have a length of 2 in the definition. When the y or Y fields are used, the number of y or Y characters in the definition determines the length of the output. For example, if you specify YYY, then the output for a value of 2006 would be 006; for a definition of YYYYYY, it would be 002006. See also Base Year below.
Extending field length: The * (asterisk) symbol is used to extend the length of a non-semantic numeric field (integers, decimals, etc). In the case of decimals, it can be used on either or both sides of the decimal point. For example, the Value Formatting *0.00* ensures that a number will have zeroes as specified in the formatting if these digit locations are empty, as well as any number of digits on both sides of the decimal point.
Entry lengths in Authentic View: The display in Authentic View of the contents of a node is based on the Value Formatting definition for that node. Therefore, the Authentic View user will not be able to insert more characters than are allowed by the Value Formatting definition. This is a useful way to restrict input in Authentic View. Note, however, that if the length of a pre-existing value in the XML document exceeds the length specified in the formatting definition, then the entire value is displayed.
| Note: | If a field does not render any text, this might be because of your region setting in Windows. For example, Windows returns an empty string for the AM/PM field if the regional language setting is German. |
Prefix and suffix modifiers
Prefix and suffix modifiers are used to modify the textual alignment and positive/negative representations of fields. The following table lists the available prefix and suffix modifiers.
Prefix | Suffix | Explanation |
< | Left aligned; default for text. For numbers, which are aligned right by default, this is significant if there are a fixed number of leading spaces. | |
> | Right aligned; default for numbers. | |
? | Minus symbol adjacent to number if negative; nothing otherwise. This is the default for numbers. | |
<? | Minus symbol left-aligned if negative; nothing otherwise. Number left-aligned, follows minus sign. | |
<?> | Minus symbol left-aligned if negative; nothing otherwise. Number right-aligned. | |
- | - | Minus symbol adjacent to number if negative; space otherwise. Located before number (prefix), after number (suffix). |
<- | >- | Minus symbol if negative; space otherwise. Number and sign adjacent. Left-aligned (prefix); right-aligned (suffix). |
<-> | Minus symbol left-aligned if negative; space otherwise. Number right-aligned. | |
+ | + | Plus or minus sign always, located adjacent to number; before number (prefix), after number (suffix). |
<+ | >+ | Plus or minus sign always, located adjacent to number; left-aligned (prefix), right-aligned (suffix). |
<+> | Plus or minus sign always, left-aligned; number right-aligned. | |
( | ) | Parentheses if negative; space otherwise. Adjacent to number. |
<( | Parentheses if negative; space otherwise. Adjacent to number. Left-aligned. | |
<(> | Parentheses if negative; space otherwise. Left parentheses left-aligned; number and right parentheses adjacent and right-aligned. | |
[ | ] | Parentheses if negative; nothing otherwise. Adjacent to number. |
* | * | Extendable number of digits to left (prefix) or to right (suffix) |
_ | _ | Space |
^ | ^ | Fill character (defined in options) |
th | Ordinality of number in EN (st, nd, rd, or th) | |
TH | Ordinality of number in EN (ST, ND, RD, or TH) |
Field options
Field options enable advanced modifications to be made to fields. The following options are available:
Option | Explanation |
uc | Make uppercase |
lc | Make lowercase |
left | Left aligned |
right | Right aligned |
ro | Read (XML) only; no editing allowed |
edit | The field is editable (active by default) |
dec=<char> | Specify a character for the decimal point (default is point) |
sep=<char> | Specify a character for the digit separator (default is comma) |
fill=<char> | Specify fill character |
base=<year> | Base year for year fields (see note below) |
pos | Show only positive numbers; input of negative numbers allowed |
Field options should be used to generate number formatting for European languages, which interchange the commas and periods of the English language system: for example, 123.456,75.
The Value Formatting to use to obtain the formatting above would be: ###,###.##{dec=,,sep=.}
Notice that the field retains the English formatting, while it is the field options dec and sep that specify the decimal symbol and digit separator. If the decimal symbol and digit separator are not specified, these characters will default to decimal symbol and digit separator of the regional settings of the Windows OS (Control Panel | All Items | Region | Format).
Note on Base Year
When using short year formats (such as yy and YY), the base year specifies a cut-off for a century. For example, the base year field option could be used in the definition DD-MM-YY{base=1940}. If the user enters a value that is equal to or greater than the last two digits of the base year, which are considered together as a two-digit positive integer, then the century is the same as that of the base year. If the value entered by the user is less than the integer value of the last two digits, then the century is the century of the base year plus one. For example if you set base=1940, then if the Authentic View user enters 50, the value entered in the XML document will be 1950; if the user enters 23, the value entered in the XML document will be 2023.
Note the following points:
•Although two digits are commonly used as the short year format, one-digit and three-digit short year formats can also be used with a base year.
•Datatypes for which short year formats can be used are: xs:date, xs:dateTime, xs:gYear, and xs:gYearMonth.
•If the Value Formatting is being set for an Auto-Calculation component, make sure that the correct datatype is selected in the Value Formatting dialog. (The selected date datatype should be that of the result to which the Auto-Calculation evaluates.)
•If the yy field type is used, the default base year is 1930. Explicitly setting a base year overrides the default.
•If the YY field type is used without any base year being set, then the Authentic View user will be able to modify only the last two digits of the four-digit year value; the first two digits remain unchanged in the XML document.