Last Updated: Aug 20, 2021
documentation for the dotCMS Content Management System

The MathTool viewtool provides methods to perform floating point math in Velocity. It utilizes the java.lang.Math class to perform calculations.

The following example shows how the ListTool is mapped in the toolbox.xml file:


Important Notes

Number Format

Most methods in this tool return numbers wrapped as Double, which automatically render the decimal places, even for whole numbers. For example, the call $math.add(1, 2).toString() returns “3.0” rather than just “3”.

  • This is intentional.
    • The MathTool tool is intended for floating point arithmetic.
    • Integer arithmetic is already supported directly by the Velocity template language.
  • If you need to convert the result of a MathTool method to an integer, use the $math.toInteger() method or call the built-in Velocity intValue() method on the result; for example:
    $math.toInteger($math.add(1, 2))
    $math.add(1, 2).intValue()

Exception Handling

None of the MathTool methods throw exceptions for null pointers, number formats, or divide by zero.

  • This is intentional (the methods are designed to intentionally fail silently), because throwing these exceptions would halt HTML rendering.
  • However even though no exceptions are thrown, you can identify errors, because when an error occurs Velocity will render the reference literally (e.g. $math.div(1, 0) renders as “$math.div(1, 0)“).

Methods and Usage

The MathTool supports the following methods:

MethodOperationReturn Value
$math.add( x, y )Additionx plus y.
$math.sub( x, y )Subtractionx minus y.
$math.mul( x, y )Multiplicationx multiplied by y.
$math.div( x, y )Divisionx divided by y.
$math.mod( x, y )ModulusThe integer remainder of integer x divided by integer y.
$math.pow( x, y )Power (Exponent)x raised to the power of y.
$math.abs( x )Absolute valueThe absolute value of x.
$math.max( x, y )MaximumThe maximum of x and y.
Note: This method accepts a maximum of 2 arguments.
$math.min( x, y )MinimumThe minimum of x and y.
Note: This method accepts a maximum of 2 arguments.
$math.ceil( x )CeilingThe smallest integer greater than or equal to x.
$math.floor( x )FloorThe integer portion of x.
$math.round( x )Roundingx rounded to the nearest whole integer.
$math.roundTo( x, y )Roundingx rounded to y decimal places.
$math.getAverage( l )AverageThe average of all values in list or collection 'l'.
See Parameters, below
$math.getTotal( l )Total (Sum)The sum of all values in list or collection 'l'.
See Parameters, below
$math.getRandom()Random numberA pseudo-random number in the range from 0 to 1.
$math.random( x, y )Random number in rangeA pseudo-random number in the range from x to y.
$math.toDouble( x )Double conversionx converted to a double.
See Parameters, below.
$math.toInteger( x )Integer conversionx converted to an integer.
See Parameters, below.


With the exception of the methods listed below, all arguments supplied to all methods must be numbers. Integer arguments will be automatically converted to floating point numbers when supplied as arguments.

Methods accepting arguments other than numbers:

MethodParameter Type(s)Example
getAverage()A list or collection containing only numbers.$math.getAverage( [ 1, 2, 3 ] )
getTotal()A list or collection containing only numbers.$math.getTotal( [ 1, 2, 3 ] )
getRandom()Does not take any arguments.getRandom()
toDouble()Either a number or a string containing a numeric format.$math.toDouble( 5 )
$math.toDouble( "5.6" )
toInteger()Either a number or a string containing a numeric format.$math.toInteger( 5.6 )
$math.toInteger( "5" )

Math in Velocity

If you are performing only simple mathematical operations, you may be able to perform them without using the MathTool. Velocity supports simple math through the use of the #set() directive, including addition, subtraction, multiplication, division and modulus. The following table shows how to use #set directive mathematical operations, in comparison to using the MathTool:

Addition#set($result = $math.add($value1, 1))#set($result = $value1 + 1)
Subtraction#set($result = $math.sub($value1, 2))#set($result = $value1 - 2)
Multiplication#set($result = $math.mul($value1, 3))#set($result = $value1 * 3)
Division#set($result = $math.div($value1, 4))#set($result = $value1 / 4)
Modulus#set($result = $math.mod($value1, 5))#set($result = $value1 % 5)

Note: The Velocity #set directive can perform mathematical operations on both integers and floating point numbers. However operations on floating point numbers are not precise, and may contain errors in far decomal places, so if calculation accuracy is important, you should use the MathTool instead of Velocity.

On this page


We Dig Feedback

Selected excerpt: