Formatting Bound Values
Value formatting functions are powerful tools that enable you to display values in specific ways in the output form without changing your data at source. Empowering template designers and breaking free from complex changes to data sources.
You can use the functions to specify the desired format. Currently, iText DITO supports Text, Number, Currency, Percentage, Date/time and Custom formatting. To configure how bound values are displayed, you select a data bind and configure the Display Format in the data properties panel.
A bind format should be specified when input data is expected in a format that is different from iText DITO's internal format.
In the example below, iText DITO reads the date-time from input data formatted in the Brussels time zone and displays the time in UTC.
Setting the bind format is especially useful if the input data contains date/time values formatted as timestamps. The internal format that iText DITO uses is ISO_8601. iText DITO will try to parse values that follow ISO_8601 compatible patterns like
date('YYYY-MM-DDTHH:mm:ss.SSZ'). For any other formats it is recommended to set the Bind Format pattern.
Number Formatting Pattern
Number formatting is represented as a string, preceded by the
num operator. A formatting string might look like this:
In the above example, there are two arguments. The first one specifies the pattern; the second argument adds a locale. A locale parameter is optional, but very handy when you want to deploy a single form in multiple geographical regions. It affects grouping, decimal separators and currency symbols.
There are six special characters you can use to define formatting. All other characters in a formatting string will be left intact.
# (Digit, zero shows as absence)
. (Decimal separator)
- (Negative sign)
, (Grouping separator)
% (Percent, multiplies number by 100)
|Format||Data Value||Formatted Result|
Date/Time Formatting Pattern
For date/time formatting, as with number formatting there are two arguments that specify the pattern, and the (optional) time zone ID. If no time zone ID is specified, then the local one will be used.
An example showing the local time and date in Paris would be formatted as follows:
date('YYYY-MM-DD HH:mm:ss ZZ', 'Europe/Paris')
ZZ in this example displays the UTC (Coordinated Universal Time) offset from the selected time zone.
The pattern consists of special characters as well as any other characters, special characters can be escaped with
M - 1 2 ... 11 12
Mo - 1st 2nd ... 11th 12th
MM - 01 02 ... 11 12
MMM - Jan Feb ... Nov Dec
MMMM - January February ... November December
Q - 1 2 3 4
Qo - 1st 2nd 3rd 4th
Day of Month:
D - 1 2 ... 30 31
Do - 1st 2nd ... 30th 31st
DD - 01 02 ... 30 31
Day of Year:
DDD - 1 2 ... 364 365
DDDo - 1st 2nd ... 364th 365th
DDDD - 001 002 ... 364 365
Day of Week:
d - 0 1 ... 5 6 do - 0th 1st ... 5th 6th
dd - Su Mo ... Fr Sa ddd - Sun Mon ... Fri Sat
dddd - Sunday Monday ... Friday Saturday
Day of Week (ISO):
E - 1 2 ... 6 7
Week of Year:
w - 1 2 ... 52 53
wo - 1st 2nd ... 52nd 53rd
ww - 01 02 ... 52 53
Week of Year (ISO):
W - 1 2 ... 52 53
Wo - 1st 2nd ... 52nd 53rd
WW - 01 02 ... 52 53
YY - 70 71 ... 29 30
YYYY - 1970 1971 ... 2029 2030
Y - 1970 1971 ... 9999 +10000 +10001
gg - 70 71 ... 29 30
gggg - 1970 1971 ... 2029 2030
Week Year (ISO):
GG - 70 71 ... 29 30
GGGG - 1970 1971 ... 2029 2030
A - AM PM
a - am pm
H - 0 1 ... 22 23
HH - 00 01 ... 22 23
h - 1 2 ... 11 12
hh - 01 02 ... 11 12
k - 1 2 ... 23 24
kk - 01 02 ... 23 24
m - 0 1 ... 58 59
mm - 00 01 ... 58 59
s - 0 1 ... 58 59
ss - 00 01 ... 58 59
S - 0 1 ... 8 9
SS - 00 01 ... 98 99 SSS - 000 001 ... 998 999
SSSS ... SSSSSSSSS - 0000.. 0010.. ... 9980.. 9990..
z/zz - EST CST ... MST PST
Z - -07:00 -06:00 ... +06:00 +07:00
ZZ - -0700 -0600 ... +0600 +0700
X - 1360013296
Unix Millisecond Timestamp:
x - 1360013296123
Notes on Date/Time Formatting
- The internal format that iText DITO uses to parse date/time values is ISO_8601. If the input data contains date/time values that follow a different pattern, it is recommended to set the Bind Format parameter.
- For month formatting, using the
MMMMpattern will not result in four-letter months, but will instead return full month names.
- If an incompatible time is parsed (one with two conflicting hours declarations for example) then an exception will be thrown.
- If the pattern doesn't contain more specific information (e.g. it contains a year but doesn't contain a month) then for more specific information the initial value will be used (first month, first day etc.)
- If the pattern doesn't contain more broad information (e.g. it contains a month and day, but doesn't contain a year) then the closest possible local information will be used (e.g. 2019 for the year etc.)
- If the pattern has a UTC (Coordinated Universal Time) offset then it will be used, and the time zone will be ignored.
- Due to DST (daylight saving time), there is a possibility that a time either does not exist, or it has previously existed.
- If you try to parse a time that never existed, it will skip forward by the amount of the DST gap (usually 1 hour).
- If you try to parse a duplicated time, then the earlier instance will be taken.
Preserving Preformatted Text
If you are binding a text string value that contains formatting tags, iText DITO can either (try to) resolve the tags or print the tags. The resolve the tags - in order to apply the formatting configuration, select the Preserve formatted text option in the data bind properties.
Supported Formatting Tags
Unsupported tags and tags with unsupported style declarations will be replaced with an empty string. All attributes except style will be ignored and removed from the tag. To activate formatting preservation, you tick the box in the data bind configuration. If you leave the box unticked all tags will be considered flat text and printed.