Data Value Formatting

Formatting Bound Values

Display Format

Value formatting functions are powerful tools that enable you to display values in specific ways in the output form. You can use the functions to specify the desired format. Currently, iText DITO supports number, currency and time/date formatting. To configure how bound values are displayed, you select a data bind and configure the Display Format in the data properties panel.

Bind Format

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.

Timestamps

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.SSSSSSZ')or date('YYYY-MM-DDTHH:mm:ss.SSZ'). For any other formats it is recommended to set the Bind Format pattern. 

Number Formatting

Number Formatting Pattern

Number formatting is represented as a string, preceded by the num operator. A formatting string might look like this:

num('$#,##0.00', 'de-de')

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.

Special Characters

There are six special characters you can use to define formatting. All other characters in a formatting string will be left intact.

• 0 (Digit)
• # (Digit, zero shows as absence)
• . (Decimal separator)
• - (Negative sign)
• , (Grouping separator)
• % (Percent, multiplies number by 100)

Examples

Date/Time Formatting

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')

The ZZ in this example displays the UTC (Coordinated Universal Time) offset from the selected time zone.

Special Characters

The pattern consists of special characters as well as any other characters, special characters can be escaped with [] brackets.

• Month:

  • 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

• Quarter:

  • 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

• Year:

  • YY - 70 71 ... 29 30

  • YYYY - 1970 1971 ... 2029 2030

  • Y - 1970 1971 ... 9999 +10000 +10001

• Week Year:

  • gg - 70 71 ... 29 30

  • gggg - 1970 1971 ... 2029 2030

• Week Year (ISO):

  • GG - 70 71 ... 29 30

  • GGGG - 1970 1971 ... 2029 2030

• AM/PM:

  • A - AM PM

  • a - am pm

• Hour:

  • 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

• Minute:

  • m - 0 1 ... 58 59

  • mm - 00 01 ... 58 59

• Second:

  • s - 0 1 ... 58 59

  • ss - 00 01 ... 58 59

• Fractional Second:

  • S - 0 1 ... 8 9

  • SS - 00 01 ... 98 99 SSS - 000 001 ... 998 999

  • SSSS ... SSSSSSSSS - 0000.. 0010.. ... 9980.. 9990..

• Time Zone:

  • z/zz - EST CST ... MST PST

  • Z - -07:00 -06:00 ... +06:00 +07:00

  • ZZ - -0700 -0600 ... +0600 +0700

• Unix Timestamp:

  • 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 MMMM pattern 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

Tags:

• <b>
• <i>
• <u>
• <strong>
• <span>

Styles: 

• font-family 
• font-weight 
• font-style 
• font-size 
• color 

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.