Formatting of numbers

How can I format a number?

As with date formatting, you can be very flexible with number formatting in your reports with Docentric Designer.

You can choose from predefined number formats, create custom formats, or specify a fixed format for a number. Let us go through these options.

Predefined number formats

You can choose from a list of predefined number formats when you click the highlighted button in the Format String dialog box.

Notice that all field tagging elements to which a format is applied have a blue icon in the Element tree. Below you can see the dialog box that opens after clicking the Format String button in the Field Properties:

Moving the mouse over a number format gives a short description and an example of the format:

image

Let us take a look at the output results we get with some of the predefined number formats:

Number format Result (en-US) Explanation
n 294,191.23 Default number format
n0 294,191 No decimal places
n2 294,191.23 Two decimal places
p 29,419,123.46% Percentage
e 2.941912e+005 Exponential (scientific)
#.00 294191.23 Fixed number of decimal places
#,# 294,191.2 Dynamic number of decimal places

As with the dates, the language of the report also impacts the number format displayed. Below you can see an example of the same number formats in English, French, and Italian in the output document:

number format and language-culture

As you can see the numbers - decimal and thousands separators - are displayed differently depending on the language.

While designing the template, we can easily change the preview language to preview the results of the number format in the specific culture (e.g., English, French or Italian).

image

However, after uploading and running the template in D365FO, the number format will be adjusted to the runtime language at report execution.

Define custom number formats

If you already know which custom number format you want to use, you can enter it directly in the Format String dialog box:

image

First, let us look at format variations you can use to display decimals. What if you need to dynamically display decimals based on the number’s current values of decimal places? For example:

  • If the decimals are zero, we need to hide the decimals;
  • If the decimals are not zero, we want them to be displayed.

We can apply the #.## number format:

#,## Unformatted number
315519,9 315519,9000000000
1234 1234,0000000000
1234,57 1234,5670000000

As you can see in the last example, the decimal places are rounded if there are more decimal places than the format specifies.

On the other hand, you can use the #.00 format to always print a certain number of decimal places regardless of their value. In the following example, I use three decimal places:

#,000 Unformatted number
315519,000 315519,0000000000
1234,000 1234,0000000000
1234,567 1234,5670000000

Since we use three zeros after the decimal point as the number format, the numbers are always printed with three decimal places, regardless of whether they are equal to zero or not.

It is also possible to combine the two number formatting options described before.

Format Result Result Result
w/o format 315519,0000000000 1234,9800100000 1234,5670100000
#.000 315519,000 1234,980 1234,567
#.00# 315519,00 1234,98 1234,567
#.0## 315519,0 1234,98 1234,567
#.### 315519 1234,98 1234,567
000000.##### 315519 001234,98001 001234,56701

The last example above shows the possibility of displaying leading zeros.

Applying number format in the Field Properties is possible only for numeric types of data fields (highlighted in the Data schema below). If we apply such formatting to, for example, a string-type data field, a warning will be displayed in the Element tree:

(Formatting of date-time types of data fields is covered here.)

How to set a fixed number format

You can use the format function to convert a numeric value to a string representation. To do this, remove the current formatting from the Field properties. Then right-click on the element to open the XPath Editor.

image

Expand the string functions and double-click to insert the format function into your existing Xpath expression.

The format function takes three parameters: the data field you want to format, the number format and (optionally) the language/culture:

format([data field], [format], [language])

Below are some examples of formatting a data field:

XPath expression Result
format(SalesInvoiceHeader/@OriginalInvoiceAmount, ‘n0’) 54.321.234
format(SalesInvoiceHeader/@OriginalInvoiceAmount, ‘n0’, ‘en-us’) 54,321,234
format(SalesInvoiceHeader/@OriginalInvoiceAmount, ‘n2’) 54.321.234,12
format(SalesInvoiceHeader/@OriginalInvoiceAmount, ‘n2’, ‘en-us’) 54,321,234.12
format(SalesInvoiceHeader/@OriginalInvoiceAmount, ‘#.###’) 54321234,123
format(SalesInvoiceHeader/@OriginalInvoiceAmount, ‘### ### ###.000000’) 54 321 234,123400
format(SalesInvoiceHeader/@OriginalInvoiceAmount, ‘#-#-#-#-#-#-#-#.##’) 5-4-3-2-1-2-3-4,12

Please note: If you do not specify the language parameter, the number (i.e., decimal separator, thousands separator) will change depending on the preview and runtime language, as already described above.

However, if you specify all three parameters of the format function, the template will show a fixed number format regardless of the preview or runtime language.