Formatting Numbers
Data Syntax
Content may contain "markers" that indicate places where data will be substituted for the markers. The marker is expressed as an HTML custom tag: <comms-data/> that contains a JSON object named "$Data". The JSON $Data object has an Id attribute.
The Id attribute is the name of the Field defined in the Assembly Template.
Example: <comms-data>$Data{"Id":"PolicyHolder"}</comms-data>
Presentation Formatting
Data in the source file may not be formatted in the desired presentation format. The data "markers" may contain an optional "format" attribute which will adjust the incoming data to match the desired presentation format.
Example:
<comms-data>$Data{"Id":"Premium","Type":"Decimal","Format":"($#,##0.00)"}</comms-data>
Structure
A "format" attribute can have up to four sections of masking characters, separated by semicolons. The sections define the format for positive numbers, negative numbers, zero values, and text, in that order.
POSITIVE;NEGATIVE;ZERO;TEXT
Each section is a valid selection of masking characters that is applied to the data based on the data's value being a positive number, negative number, zero or a non-numeric.
Example:
(#,##0.00);(#,##0.00);0.00;'sales '@
Example:
<comms-data>$Data{"Id":"Premium", "Format":"(#,##0.00);(#,##0.00);0.00;'sales '@"}</comms-data>
Note:
All sections are not required.- One section: The format will apply to all numbers
- Two sections: The first section will apply to non-negative numbers (>=0) and the second will apply to negative numbers (<0).
- Three sections: The first will apply to positive numbers (>0), the second to negative numbers (<0) and the third to zero (=0).
- Four sections: The first will apply to positive numbers (>0), the second to negative numbers (<0), the third to zero (=0) and the fourth to non-numerics.
Blank sections may be included and will result in no output for data that meets the blank sections criteria. Blank sections must be identified using the semicolon (;) delimiter.
Example:
POSITIVE;;;TEXT would result in the POSITIVE section being applied to positive numbers (>0), no output for zero (-0) or negative (<0) numbers and the TEXT section applied to non-numerics.
If the data value is non-numeric (alpha) and there is no TEXT section no data will be displayed in the output. E.g. Given a pattern of #,##0.00 and data of "hello" the output would be empty.
In the absence of a NEGATIVE section the negative sign (-) is displayed for negative numbers. E.g. Given a pattern of #,##0.00 and data of -23456 the output would be -23,456.00.
In the presence of a NEGATIVE section the negative sign (-) is NOT displayed for negative numbers. E.g. Given a pattern of #,##0.00;#,##0.00 and data of -23456 the output would be 23,456.00.
Numeric Formatting
Numeric formatting can be applied to any incoming string or numeric data.
Data
Table 4-1 Masking Characters
| Mask | Purpose | Special Conditions and Notes |
|---|---|---|
| 0 | Displays a zero if there is no digit; otherwise displays the digit. | A 0 will display a zero digit so numbers less than 1 and greater than -1 will display a leading zero if there is a 0-place holder to the left of the decimal. |
| # | Displays the digit in the position or nothing if there is no digit. | A # will not display a zero digit so numbers less than one and greater than -1 will display without a leading zero before the decimal if there are only # place holders to the left of the decimal. |
| . | Displays the decimal point of the number within the pattern. |
The number will be rounded to the number of placeholders (# or 0) using the default Java round() rle that follows the "Round half away from zero" methodology. If the fraction of x is exactly 0.5, then y = x + 0.5 if x is positive, and y = x − 0.5 if x is negative. For example, 23.5 gets rounded to 24, and −23.5 gets rounded to −24. Extra digits to the left of the decimal are always displayed. A # will not display a zero digit so numbers less than one and greater than -1 will display without a leading zero before the decimal if there are only # place holders to the left of the decimal. A 0 will display a zero digit so numbers less than 1 and greater than -1 will display a leading zero if there is a 0-place holder to the left of the decimal. If there is no dot (.) in the mask numbers will be rounded to a whole number following the same rounding methodology as noted above. |
| , | Displays the thousands separator in a number when enclosed in a combination of 0 and/or # markers. | The comma (,) will be ignored if not placed in the thousands position within the mask set. |
| 'text' | Any alphanumeric strings between two single quotes will be displayed verbatim. | Single quote marks (') must be used. Double quote marks (") are not valid. The variation is adopted to facilitate JSON and HTML syntax that is being used. |
| % | Will display the percent symbol and will convert the data to a percentage of 100. | Converts the incoming data to a percentage of 1 so .04 will display as 4% and 4 will display as 400%. |
| $ | Will display the currency symbol based on the locale. | If no locale is specified, the U.S. dollar sign will be displayed. |
| + | Will display the plus sign | |
| = | Will display the equal sign | |
| - | Will display the minus sign | |
| ( | Will display the left parenthesis | |
| ) | Will display the right parenthesis | |
| Will display a single space | ||
| @ | Will display the text value of the incoming data. |
Examples
The following table illustrates the impact of different numeric format strings on incoming data.
Table 4-2 Numeric format strings and incoming data
| Data/Format Structure | #,###.## | #,###.##0 | #,###.# | #,### |
|---|---|---|---|---|
| 123456.78 | 123,456.78 | 123,456.78 | 123,456.80 | 123,457 |
| 123456 | 123,456 | 123,456.00 | 123,456 | 123,456 |
| -123456.78 | -123,456.78 | -123,456.78 | -123,456.80 | -123,457 |
| -123456 | -123,456 | -123,456.00 | -123,456 | -123,456 |
| Hello | ||||
| 0 | 0 | 0 | 0 | 0 |
| Data/Format Structure | # | #,###.00;(#,###.00) | #,###.00;(####.00) | $###0;$(###0) |
| 123456.78 | 123457 | 123,456.78 | 123,456.78 | $123,457 |
| 123456 | 123456 | 123,456.00 | 123,456.00 | $123,456 |
| -123456.78 | -123457 | -123,456.78 | -123456.78 | ($123,457) |
| -123456 | -123456 | -123,456.00 | -123456 | ($123,456) |
| Hello | ||||
| 0 | 0 | 0 | 0 | 0 |
| Data/Format Structure | 'Good';'Bad' | 'Pos: '#;'Neg: '#;'Zero' | 'Pos: '#.0;'Neg: '#.0;'Zero';'Other' | #;#;#;@ |
| 123456.78 | Good | Pos: 123457 | Pos: 123456.8 | 123457 |
| 123456 | Good | Pos: 123456 | Pos: 123456.0 | 123456 |
| -123456.78 | Bad | Neg: 123457 | Neg: 123456.8 | 123457 |
| -123456 | Bad | Neg: 123456 | Neg: 123456.0 | 123456 |
| Hello | Other | Hello | ||
| 0 | Good | Zero | Zero | 0 |
| Data/Format Structure | +#;-#;'x';'t: '@ | +# | -# | |
| 123456.78 | 123457 | 123457 | -123457 | |
| 123456 | 123456 | 123456 | -123456 | |
| -123456.78 | -123457 | -123457 | 123457 | |
| -123456 | -123456 | -123456 | 123456 | |
| Hello | t: Hello | |||
| 0 | x | + |