On line guide/help

You are on page 41 of the online help. Navigate sequentially through the guide pages or search for a topic of interest to you.

Index Prev. Next

Data

Value formatting

Format numbers, percentages and currency values

A format mask formats a numeric value before it is printed. It can be used in the format attribute of the box element, of the chart measures (values printed by the bar chart) and of the gauge, KPI and pie charts (version 1.0.11 or later). The aliases valueformat, mask and valuemask can also be used.

Format masks

A mask is made of up to three parts: type + decimals (one digit) + symbol. Examples with the default settings:

F Float number. Eg. F2 : 1.234,50
I Integer number, without decimals. Eg. I : 1.235
P or % Percentage (the value is not multiplied by 100). Eg. P1 : 12,5 %
C Currency. Eg. C2 $ : 1.234,50 $
N None: prints an empty string
Any other mask prints the value as it is (unless a custom format callback is set, see below).

If the decimals digit is not set, the default number of decimals is used. The symbol is used only by the P and C types and it is written after the decimals digit, including the leading space if required: to set a symbol, the decimals digit must also be set (eg. C0 €). Without the symbol, P prints " %" and C prints the currency symbol set in the CURRENCYSYMBOL variable. The F and I types add the symbol set in the NUMERICSYMBOL variable.

Format masks in box elements

Default format settings

The default settings are stored in system variables, that can be changed with SetVar in the PHP code or with the var element in the template:

NUMERICDECIMALSEPARATOR Decimal separator (default ,)
NUMERICTHOUSANDSEPARATOR Thousands separator (default .)
NUMERICDECIMALCOUNT Decimals of the F and P types (default 2)
CURRENCYDECIMALCOUNT Decimals of the C type (default 2)
CURRENCYSYMBOL Symbol of the C type (default: a space followed by €)
NUMERICSYMBOL Symbol added to the F and I types (default: empty)

Change the default format settings

Custom format callback

With the SetFormatCallback method a PHP function can format the values. The function receives the mask and the value, and returns the formatted value; if it returns an empty string, the standard format is applied. The mask can be any text, so custom masks can be defined (eg. DATE_EU).

Custom format callback

The custom mask is then used in the template like the standard masks: