Calculations

Sometimes, it might be impossible to show the necessary information on the output form using only data binding. You might for example want to show a total at the end of an invoice, containing the sum of all items ordered in their respective quantities, multiplied by the VAT. Or just format the time/date to your region standard.

In order to simplify processing of the data without the need for pre-processing, iText DITO can handle many straightforward and more complex calculations.

Inserting a Calculation

Calculations can be inserted into rich text elements. To insert a calculation, click the f(x) icon in the command bar. Bear in mind that it can be hidden under the ellipsis (three vertical dots) icon.

Straightforward Calculations

iText DITO supports the following functions:

And the following operators:

"+", "-", "*", "/"

Example

Imagine you are designing a report on consumption of service hours. The customer has a certain entitlement of support hours and has consumed some of those. Your report should calculate the total amount due for the hours consumed and the remainder of the entitlement. The data contains only these fields:

{{service_hour_entitlement}}, {{service_hour_consumption}}, {{service_hour_unit_price}}

To calculate the total amount due, you can use the product() function 

To calculate the remainder of the service entitlement, you can use the sum() function

Calculations within Loops

All of the straightforward calculations can be used inside a repeatable element, like a table row that repeats for all items on an invoice template. In that case make sure to use relative references to the data elements.

Supported Calculations

It is also possible to calculate a field using other fields which are the results of calculations themselves. In order to perform calculations on the variables in a field, you must name the fields. The field names act as variables that you can use in mathematical expressions.

Arguments are the names of the fields that are referred in the calculation expression. Function arguments refer to the fields in the way similar to binding. The reason they refer to fields is that some fields may not be bound to a value, e.g. calculated fields. If you want to use a specific value from provided data, you can create a hidden field with read-only binding.

If you want to calculate the function based on the variable number of fields all of which have the same name, you can also use the "[*]" notation.

You can also enter expressions in a free form. The supported mathematical operators are "+", "*", "-", "/". We also support relative operators: ">", "<", ">=", "<=", negation operator: "!", equality operators: "==", "!=", and if else operator: "?:"

See below the current supported calculations:

1. sum(...) - sums passed arguments, accepts varargs, requires at least one parameter
2. product(...) - multiplies passed arguments, accepts varargs, requires at least one parameter

3. concat(...) - concatenates string representation of passed arguments, accepts varargs, requires at least one parameter. Next to the arguments to be concatenated, concat function accepts an optional named parameter called separator which specifies delimiter to be used during concatenation. By default the delimiter is empty string, i.e. all the strings are just appended one to another sequentially.

4. moneyToText(value, locale) - converts number to text in local language with local currency names. locale is an optional parameter. Element locale will be used by default.
5. numberToText(value, locale) - converts number to text in local language. locale is an optional parameter. Element locale will be used by default.
6. min(...) - finds minimal argument, accepts varargs, requires at least one parameter
7. max(...) - finds maximal argument, accepts varargs, requires at least one parameter
8. (deprecated) contains(string, substring) - checks whether string contains substring, requires at least two parameter
9. stringContains(string, substring, [ignoreCase=true|false]) - checks whether string contains substring, accepts optional  ignoreCase argument (default value is false), requires at least two parameters
10. stringEquals(first, second, [ignoreCase=true|false]) - checks whether string first is equal to string second, accepts optional ignoreCase argument (default value is false), requires at least two parameters
11. isEmpty(string) - checks whether string is an empty string ""
12. isBlank(string) - checks whether string is an empty string "" or consist only of spaces e.g. "   "
13. size(...) - gets the number of passed arguments, accepts varargs (e.g. size({{array[*]}}) will return number of elements in array in data)
14. filterNotNull(...) - filters passed arguments and leaves only not null values, accepts varargs e.g. filterNotNull({{array[*]}}). Is intended to be used as intermediate function in other functions that accepts varargs e.g. size(filterNotNull({{array[*]}})) will return number of not null elements in array.
15. currentTimestamp() - returns current date/time in ISO-8601 format.
16. formatDate(date, pattern, timeZone, locale) - formats the date to text using the pattern.
17. parseDate(date, pattern, timeZone, locale) - parse date text into ISO-8601 format.
18. formatNum(num, pattern, locale, currencySymbol, groupingSeparator, decimalSeparator) - formats number to text using specified pattern.
19. parseNum(num, pattern, locale, currencySymbol, groupingSeparator, decimalSeparator) - parses number text using pattern provided.

Example

In the example below the aim is to calculate a grand total based on calculated subtotals.

First, create a table with repeating rows for each item in an array. In the last cell of the row, insert a rich text element with a product() calculation. 

To be able to use that product() in another calculation, give the rich text element a name.

You can now use this name in other calculations, for instance to calculate the grand total. Note that you don't use double curly braces to refer to this named field. the double curly braces are only used to refer to elements in the data sample.