Skip to main content
Skip table of contents

.Data Value Formatting viText_DITO_1.3

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.

image2020-3-6_14-34-12.png

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

FormatData ValueFormatted Result
num('$#,##0.00', 'de-de')4500.20

€4.500,20

num('$#,##0.00', 'en-us')4500.20$4,500.20
num('#0.00')0.20.20
num('#0.##%')0.220%


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.





JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.