Skip to main content

Expressions

Create dynamic labels using expressions.

Introduction

Expressions extend label tokens to allow mathematical manipulation of those values. This in effect removes the need for label callback functions and is a much simpler alternative. Expressions can be a powerful technique with functionality that can be written in a short string that would otherwise require a lot of code writing label callback functions.

Expressions within a string much be surrounded with '{ }' characters.

The basic syntax for an expression is:

{(expression)}

Expression with format string.

{(expression):(formatString)}

Expressions can contain tokens and numbers included in the calculations.

Default Formatting

When an expression like '{%yValue/%percentOfSeries}' is used, the default formatting of the first token is applied to the result. In this case the formatting of the yAxis would apply.

Calculations

Basic Calculation Features

Standard calculation operators such as / * - + can be used within the label expression. For example:

Examples

ExpressionDescription
'{%value/1000}K'Converts numbers such as '56,000' into '56K'.
'{%value/1000000:n1}M'Converts numbers such as '56,500,000' into '56.5M'.
'{%value*5}'If the token represents a value such as '20', this label will result in '100'
'{%yValue/%percentOfSeries}'Multiple tokens can be used within an expression.
'{(%value+5)*5}'Parentheses can also be used in expressions.
'{%yValue*100/%percentOfSeries:n}'This calculates the series y value total at the data point label level.

Date Calculations

Tokens which represent dates like with date axis ticks, '{%value}' will result in a date, but if expressions are used, the dates are converted to numbers.
Formatting can be specified within the expression which will convert the value back to a date.

Explicit Data Type Formatting

Generally since the formatting of the first token in the expression is used for the resulting format, if the first token is associated with dates, it will automatically be converted back to a date. In cases where this is not done automatically, the following syntax can be used for force the values to become either numbers or dates.

{(expression):Date (formatString)}
{(expression):Number (formatString)}

Date Expression Methods

Several date related helper functions are available to use in date calculations. These functions are listed below.

  • days()
  • weeks()
  • years()
  • hours()
  • minutes()
  • seconds()

Examples

ExpressionDescription
'{%value+days(5):Date d}'Adds 5 days to the date represented by the %value token.
'{%value-years(1):Date d}'Subtracts 1 year from the date represented by the %value token.

Time Spans

The date functions can also be utilized to calculate date ranges. For instance consider two tokens: 'xMin', and 'xMax'.
These represent the minimum and maximum X axis date ranges.

ExpressionDescription
'{days(%xMax-%xMin)}:Number n}'The number of days between the max and min X axis time span.
'{months(%xMax-%xMin)}:Number n2}'The number of months between the max and min X axis time span formatted with two decimal points.
'{years('+Date.now()+'-%since):number n1}'Calculates how many years have lapsed since the date represented by the %since token.
'{%total/years('+Date.now()+'-%since):number n1}'Calculates how many years have lapsed since the date represented by the %since token. Then shows the average per year based on the %total token.

Tip: By including Date.now() within a string, the current date can be used with calculations. For example: '{years('+Date.now()+'-%since)}'

Percent Of Calculations

Percentages are calculated based on current value / sum. However, the sum in this calculation is the points range from yStart or 0 to y. And the absolute values are used. So to sum up y values the following calculation is used:

Sum += Math.abs(y - (yStart || 0));