Tokens

Overview

ZingChart tokens act as variables for different value types. Known as string interpolation or variable substitution, the token will return the applicable value when it is called. This tutorial organizes the tokens according to whether they're tied to the:

• Nodes
• Scales
• Time-Series
• Other (legend tooltips, standalone labels)

The majority of the tokens are tied to the nodes (or data points), and can be used with tooltips, value boxes, crosshair plot labels, and rules. There are also tokens tied to the scales, which can be used with the x- and y-axis scales, crosshair scale labels, and scale tooltips. With time-series data, tokens are used to specify how the Unix timestamps are formatted. There are also a limited number of tokens that can be used with legends and standalone labels.

Math Operations

ZingChart supports basic math operations with evaluated tokens. Just place your math expression containing token(s) within two curly brackets. Any constructs between the brackets will be evaluated after all tokens have been parsed.

valueBox: {
  text: 'Double the value: {{ %v * 2 }}'
}

Tokens List

Here is a full list of currently available tokens, provided in alphabetical order.

Nodes

Most of our tokens are tied to the node value, or the data points that make up your chart. Node tokens can be used with tooltips, value boxes, crosshair plot labels, and rules, as the following chart examples using the %v token (representing the node value) demonstrate.

Tooltips

Tooltips are the labels that appear when you hover over the node values, and they appear by default across our charting library.

{
  type: "area",
  title: {
    text: "Tooltips"
  },
  plot: {
    tooltip: {
      text: "Node Value: %v"
    }
  },
  series: [{
    values: [30, 34, 14, 15, 31, 35]
  }]
}

Value Boxes

Value boxes are fixed labels that appear on or around the node values. They can be used to emphasize or draw attention to specific data points.

{
  type: "area",
  title: {
    text: "Value Boxes"
  },
  plot: {
    'value-box': {
      text: "Node Value: %v"
    },
    tooltip: {
      visible: false
    }
  },
  series: [{
    values: [30, 34, 14, 15, 31, 35]
  }]
}

Crosshair Plot Labels

Crosshairs are another type of hover label with two parts: the plot label (upper label) and the scale label (lower label). The plot label portion (shown in the below example) is tied to the nodes. The scale label portion (see the Crosshair Scale Labels section further below) is tied to the scales.

{
  type: "area",
  title: {
    text: "Crosshair Plot Labels"
  },
  'crosshair-x': {
    'plot-label': {
      text: "Node Value: %v"
    },
    'scale-label': {
      visible: false
    }
  },
  plot: {
    tooltip: {
      visible: false
    }
  },
  series: [{
    values: [30, 34, 14, 15, 31, 35]
  }]
}

Rules

Rules allow you to customize the appearance of your chart based on specified conditions. In the following chart, rules were used to define the line, background, and marker colors based on the node value. See the Logic Rules Tutorial for more information.

{
  type: "area",
  title: {
    text: "Rules"
  },
  plot: {
    rules: [{
      rule: "%v <=35 && %v > 34",
      'line-color': "purple",
      'background-color': "purple"
    }, {
      rule: "%v <=34 && %v > 31",
      'line-color': "blue",
      'background-color': "blue"
    }, {
      rule: "%v <= 31 && %v > 30",
      'line-color': "green",
      'background-color': "green"
    }, {
      rule: "%v <= 30 && %v > 25",
      'line-color': "yellow",
      'background-color': "yellow"
    }, {
      rule: "%v <= 25 && %v > 14.5",
      'line-color': "orange",
      'background-color': "orange"
    }, {
      rule: "%v <= 14.5",
      'line-color': "red",
      'background-color': "red"
    }],
    marker: {
      rules: [{
        rule: "%v <=35 && %v > 34",
        'background-color': "purple"
      }, {
        rule: "%v <=34 && %v > 31",
        'background-color': "blue"
      }, {
        rule: "%v <= 31 && %v > 30",
        'background-color': "green"
      }, {
        rule: "%v <= 30 && %v > 25",
        'background-color': "yellow"
      }, {
        rule: "%v <= 25 && %v > 14.5",
        'background-color': "orange"
      }, {
        rule: "%v <= 14.5",
        'background-color': "red"
      }]
    }
  },
  series: [{
    values: [30, 34, 14, 15, 31, 35]
  }]
}

Scales

Scales are distinct from nodes, and they use their own %v token (corresponding to the scale value). The scale value token (%v) is distinct from the node value token (%v), despite sharing the same name. The scale value token is used specifically for scale-related items, and can be used with the x-axis scale, y-axis scale, crosshair scale labels, and scale tooltips, as the following chart examples demonstrate. Refer to the Configuring the X/Y-Axis Scales Tutorial for more information on the different scale types (linear, logarithmic, category, time-series).

X-Axis Scale

You can format the appearance of the scale values by using the format attribute and %v scale value token in the scale-x object. Refer to the Scales Tutorial for more information and examples as how you format the scale labels will often depend on the type of scale used (linear, time-series, category).

{
  type: "area",
  title: {
    text: "X-Axis Scale"
  },
  'scale-x': {
    format: "Scale Value: %v"
  },
  plotarea: {
    'margin-bottom': "dynamic"
  },
  series: [{
    values: [30, 34, 14, 15, 31, 35]
  }]
}

Y-Axis Scale

Use the format attribute and %v scale value token in the scale-y object to format the appearance of the scale values. See the Scales Tutorial for more information and examples as how you format the scale labels will often depend on the type of scale used (linear, logarithmic, category).

{
  type: "area",
  title: {
    text: "Y-Axis Scale"
  },
  'scale-y': {
    format: "Scale Value: %v"
  },
  plotarea: {
    'margin-left': "dynamic"
  },
  series: [{
    values: [30, 34, 14, 15, 31, 35]
  }]
}

Crosshair Scale Labels

Crosshairs are another type of hover label with two parts: the plot label (upper label) and the scale label (lower label). The scale label portion (shown in the below example) is tied to the scale. The plot label portion (see the Crosshair Plot Labels section further above) is tied to the node.

{
  type: "area",
  title: {
    text: "Crosshair Scale Labels"
  },
  'crosshair-x': {
    'plot-label': {
      visible: false
    },
    'scale-label': {
      text: "Scale Value: %v"
    }
  },
  plot: {
    tooltip: {
      visible: false
    }
  },
  series: [{
    values: [30, 34, 14, 15, 31, 35]
  }]
}

Scale Tooltips

Scale tooltips appear when you hover over the labels on the x- and/or y-axis. Note that the tooltip object with text attribute must be added to each scale object you want the tooltips to appear for.

{
  type: "area",
  title: {
    text: "Scale Tooltips"
  },
  subtitle: {
    text: "Hover over the scale labels"
  },
  'scale-x': {
    tooltip: {
      text: "Scale Value: %v"
    }
  },
  'scale-y': {
    tooltip: {
      text: "Scale Value: %v"
    }
  },
  series: [
    {
      values: [30,34,14,15,31,35]
    }
  ]
}

Time-Series

ZingChart accepts Unix time values in milliseconds, which are then converted into a readable format on your chart. Our time-series tokens were created for the specific purpose of formatting that time-series data. That formatting is done inside a transformobject. In the object, you must add a type attribute with the value set to date. You must also add an all attribute. The value will be the time-series tokens and/or alphanumeric characters you want displayed. Time-series tokens can be used with the x-axis scale, y-axis scale, tooltips, value boxes, and crosshairs (both plot and scale labels).

Tokens List

Here is a full list of currently available time-series tokens, provided in alphabetical order.

X-Axis Scale

Time-series formatting starts with the x-axis scale. In the scale-x object, specify your minimum (min-value) and step (step) scale values. In the transform object, add a type and all attribute. Refer to the Configuring the X/Y-Axis Scales Tutorial for more information.

{
  type: "line",
  title: {
    text: "X-Axis Scale"
  },
  'scale-x': {
    'min-value': "1457101800000",
    'max-value': "1457125200000",
    step: "30minute",
    transform: {
      type: "date",
      all: "%g:%i"
    },
    label: {
      text: "Trading Day"
    },
    item: {
      'font-size': 10
    },
    'max-items': 14
  },
  utc: true,
  timezone: -5, //EST time
  'scale-y': {
    values: "30:34:1",
    format: "$%v",
    label: {
      text: "Price"
    },
    item: {
      'font-size': 10
    },
    guide: {
      'line-style': "solid"
    }
  },
  series: [{
    values: [
      [1457101800000, 30.34], //03/04/2016 at 9:30 a.m. EST (which is 14:30 in GMT)
      [1457103600000, 31.30], //10:00 a.m.
      [1457105400000, 30.95], //10:30 a.m.
      [1457107200000, 30.99], //11:00 a.m.
      [1457109000000, 32.33], //11:30 a.m.
      [1457110800000, 33.34], //12:00 p.m.
      [1457112600000, 33.01], //12:30 p.m.
      [1457114400000, 34], //1:00 p.m.
      [1457116200000, 33.64], //1:30 p.m.
      [1457118000000, 32.59], //2:00 p.m.
      [1457119800000, 32.60], //2:30 p.m.
      [1457121600000, 31.99], //3:00 p.m.
      [1457123400000, 31.14], //3:30 p.m.
      [1457125200000, 32.34], //at 4:00 p.m. EST (which is 21:00 GMT)
    ]
  }]
}

Y-Axis Scale

While less commonly used, you can also create a time-series scale on the y-axis. In the scale-y object, specify your minimum (min-value) and step (step) scale values. In the transform object, add a type and all attribute. Refer to the Configuring the X/Y-Axis Scales Tutorial for more information.

{
  type: 'bar',
  title: {
    text: "Y-Axis Scale"
  },
  plot: {
    'bar-width': "50%",
    stacked: true,
    tooltip: {
      text: "Raise %plot-text by %scale-value-value",
      transform: {
        type: "date",
        all: "%g:%i %A"
      }
    },
  },
  'scale-x': {
    labels: [ "A's Goal", "B's Goal", "C's Goal" ],
    label: {
      text: "12-Hour Fundraiser"
    },
    item: {
      'font-size':10
    },
  },
  'scale-y': {
    'min-value': "1457091000000", //6 AM
    'max-value': "1457132400000", //Midnight
    step: "3600000", //1 hour
    transform: {
      type: "date",
      all: "%g:%i %a"
    },
    label: {
      text: "Time"
    },
    item: {
      'font-size':10
    },
  },
  utc: true,
  timezone:-5, //EST time
  plotarea: {
    'margin-left': "15%"
  },
  series: [
    {
      values: [1457110800000, 1457107200000, 1457103600000],
      text: "300K"
    },
    {
      values: [7200000, 7200000, 12600000],
      text: "350K"
    },
    {
      values: [7200000, 7200000, 5400000],
      text: "400K"
    },
    {
      values: [3600000, 5400000, 3600000],
      text: "450K"
    },
    {
      values: [3600000, 5400000, 7200000],
      text: "500K"
    }
  ]
}

Tooltips

Use the %kv token to display time-series values in the tooltips. You can also change the formatting of that time-series data (e.g., to show the full date or a shortened version of it) by adding a transform object to the tooltip object. Add a type attribute (with value set to date) and all attribute (with desired formatting contained in quotes).

{
  type: "line",
  title: {
    text: "Tooltips"
  },
  plot: {
    tooltip: {
      text: "%kv",
      transform: {
        type: "date",
        all: "%g:%i %a<br>on<br>%M %d, %Y"
      }
    }
  },
  'scale-x': {
    'min-value': "1457101800000",
    'max-value': "1457125200000",
    step: "30minute",
    transform: {
      type: "date",
      all: "%g:%i"
    },
    label: {
      text: "Trading Day"
    },
    item: {
      'font-size': 10
    },
    'max-items': 14
  },
  utc: true,
  timezone: -5, //EST time
  'scale-y': {
    values: "30:34:1",
    format: "$%v",
    label: {
      text: "Price"
    },
    item: {
      'font-size': 10
    },
    guide: {
      'line-style': "solid"
    }
  },
  series: [{
    values: [
      [1457101800000, 30.34], //03/04/2016 at 9:30 a.m. EST (which is 14:30 in GMT)
      [1457103600000, 31.30], //10:00 a.m.
      [1457105400000, 30.95], //10:30 a.m.
      [1457107200000, 30.99], //11:00 a.m.
      [1457109000000, 32.33], //11:30 a.m.
      [1457110800000, 33.34], //12:00 p.m.
      [1457112600000, 33.01], //12:30 p.m.
      [1457114400000, 34], //1:00 p.m.
      [1457116200000, 33.64], //1:30 p.m.
      [1457118000000, 32.59], //2:00 p.m.
      [1457119800000, 32.60], //2:30 p.m.
      [1457121600000, 31.99], //3:00 p.m.
      [1457123400000, 31.14], //3:30 p.m.
      [1457125200000, 32.34], //at 4:00 p.m. EST (which is 21:00 GMT)
    ]
  }]
}

Value Boxes

To display time-series values in the value boxes, use the %kv token. To change the time-series formatting, add a transform object to the value-box object. Make sure to add a type attribute (with value set to date) and all attribute (with desired formatting contained in quotes).

{
  type: "line",
  title: {
    text: "Value Boxes"
  },
  plot: {
    'value-box': {
      text: "%kv",
      transform: {
        type: "date",
        all: "%G:%i:%s"
      }
    }
  },
  'scale-x': {
    'min-value': "1457101800000",
    'max-value': "1457125200000",
    step: "30minute",
    transform: {
      type: "date",
      all: "%g:%i"
    },
    label: {
      text: "Trading Day"
    },
    item: {
      'font-size': 10
    },
    'max-items': 14
  },
  utc: true,
  timezone: -5, //EST time
  'scale-y': {
    values: "30:34:1",
    format: "$%v",
    label: {
      text: "Price"
    },
    item: {
      'font-size': 10
    },
    guide: {
      'line-style': "solid"
    }
  },
  series: [{
    values: [
      [1457101800000, 30.34], //03/04/2016 at 9:30 a.m. EST (which is 14:30 in GMT)
      [1457103600000, 31.30], //10:00 a.m.
      [1457105400000, 30.95], //10:30 a.m.
      [1457107200000, 30.99], //11:00 a.m.
      [1457109000000, 32.33], //11:30 a.m.
      [1457110800000, 33.34], //12:00 p.m.
      [1457112600000, 33.01], //12:30 p.m.
      [1457114400000, 34], //1:00 p.m.
      [1457116200000, 33.64], //1:30 p.m.
      [1457118000000, 32.59], //2:00 p.m.
      [1457119800000, 32.60], //2:30 p.m.
      [1457121600000, 31.99], //3:00 p.m.
      [1457123400000, 31.14], //3:30 p.m.
      [1457125200000, 32.34], //at 4:00 p.m. EST (which is 21:00 GMT)
    ]
  }]
}

Crosshairs

The transform object can be used in both the plot and scale label portions of the crosshairs. However, remember that the plot-label object is tied to the nodes and the scale-label object is tied to the scales. This means that in the former, it is the %kvtoken (representing the parsed scale value) that corresponds to the time-series data. (In this portion, the %v token corresponds to the node value.) In the latter, it is the %v token (which, in this portion, is the scale value) that corresponds to the time-series data.

{
  type: "line",
  title: {
    text: "Crosshairs"
  },
  'crosshair-x': {
    'plot-label': { //tied to nodes.
      text: "$%v at %kv", //%kv is the parsed scale value
      transform: {
        type: "date",
        all: "%g:%i %A"
      }
    },
    'scale-label': { //tied to scales.
      text: "on %v", //%v is the scale value
      transform: {
        type: "date",
        all: "%D, %m/%d/%y"
      }
    }
  },
  plot: {
    tooltip: {
      visible: false
    }
  },
  'scale-x': {
    'min-value': "1457101800000",
    'max-value': "1457125200000",
    step: "30minute",
    transform: {
      type: "date",
      all: "%g:%i"
    },
    label: {
      text: "Trading Day"
    },
    item: {
      'font-size': 10
    },
    'max-items': 14
  },
  utc: true,
  timezone: -5, //EST time
  'scale-y': {
    values: "30:34:1",
    format: "$%v",
    label: {
      text: "Price"
    },
    item: {
      'font-size': 10
    },
    guide: {
      'line-style': "solid"
    }
  },
  series: [{
    values: [
      [1457101800000, 30.34], //03/04/2016 at 9:30 a.m. EST (which is 14:30 in GMT)
      [1457103600000, 31.30], //10:00 a.m.
      [1457105400000, 30.95], //10:30 a.m.
      [1457107200000, 30.99], //11:00 a.m.
      [1457109000000, 32.33], //11:30 a.m.
      [1457110800000, 33.34], //12:00 p.m.
      [1457112600000, 33.01], //12:30 p.m.
      [1457114400000, 34], //1:00 p.m.
      [1457116200000, 33.64], //1:30 p.m.
      [1457118000000, 32.59], //2:00 p.m.
      [1457119800000, 32.60], //2:30 p.m.
      [1457121600000, 31.99], //3:00 p.m.
      [1457123400000, 31.14], //3:30 p.m.
      [1457125200000, 32.34], //at 4:00 p.m. EST (which is 21:00 GMT)
    ]
  }]
}

Other

There are a limited number of tokens that can be used with legend tooltips and standalone labels.

Legend Tooltips

Legend tooltips appear when users hover over the items in the legend. They support a limited number of tokens:

To create legend tooltips, add a tooltip object to the legend object. Include the tokens in the tooltip's text attribute.

{
  type: 'bar',
  title: {
    text: "Legend Tooltips"
  },
  legend: {
    x: "25%",
    y: "12%",
    layout: "horizontal",
    tooltip: { //Legend Tooltips
      text: "The %plot-text population is %plot-description",
      width: "20%",
      height: "20%",
      'wrap-text': true,
      padding: "5%",
      'background-color': "white",
      'font-color': "black",
      'font-family': "Georgia",
      'border-width': 1,
      'border-color': "gray",
      'border-radius': "5px",
      sticky: true,
      timeout: 10000
    }
  },
  plotarea: {
    'margin-top': "25%"
  },
  plot: {
    stacked: true,
    'bar-width': "30%"
  },
  'scale-x': {
    labels: [ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M" ]
  },
  'scale-y': {
    values: "0:200:50"
  },
  series: [{
    values: [64, 59, 55, 49, 39, 35, 31, 20, 16, 15, 9, 5, 4],
    text: "0-18 years",
    description: "depicted in blue."
  }, {
    values: [99, 90, 87, 70, 59, 51, 45, 39, 34, 25, 21, 9, 5],
    text: "18-64 years",
    description: "depicted in red."
  }, {
    values: [34, 30, 16, 15, 14, 12, 10, 9, 8, 7, 5, 4, 3],
    text: "65 and over",
    description: "depicted in green."
  }]
}

Standalone Labels

Standalone labels differ from other label types (tooltips, value boxes, crosshairs) because they are not tied in any way to the nodes. They support a limited number of tokens:

Because standalone labels are not tied to the nodes, the relationship to a series or node must be called out specifically. To add standalone labels, create a labels array. Inside the array, create an object for each label. Refer to the Labels Tutorial for more information. In the following chart, three labels were created.

{
  type: 'bar',
  title: {
    text: "Standalone Labels"
  },
  labels: [{ //Label One
    text: "0-18 years: %plot-0-value",
    'default-value': "___", //optional placeholder for token text
    height: "7%",
    width: "23%",
    x: "15%",
    y: "12%",
    'text-align': "left", //to keep text stationary
    'font-color': "black",
    'font-family': "Georgia",
    'border-width': 2,
    'border-color': "#29A2CC",
    'border-radius': "5px",
    'padding-left': "30%"
  }, { //Label Two
    text: "18-64 years: %plot-1-value",
    'default-value': "___",
    height: "7%",
    width: "23%",
    x: "40%",
    y: "12%",
    'text-align': "left",
    'font-color': "black",
    'font-family': "Georgia",
    'border-width': 2,
    'border-color': "#D31E1E",
    'border-radius': "5px",
    'padding-left': "30%"
  }, { //Label Three
    text: "65 and over: %plot-2-value",
    'default-value': "___",
    height: "7%",
    width: "23%",
    x: "65%",
    y: "12%",
    'text-align': "left",
    'font-color': "black",
    'font-family': "Georgia",
    'border-width': 2,
    'border-color': "#7CA82B",
    'border-radius': "5px",
    padding: "30%"
  }],
  plotarea: {
    'margin-top': "25%"
  },
  plot: {
    stacked: true,
    'bar-width': "30%",
    tooltip: {
      visible: false
    }
  },
  'crosshair-x': {
    'plot-label': {
      visible: false
    }
  },
  'scale-x': {
    labels: [ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M" ]
  },
  'scale-y': {
    values: "0:200:50"
  },
  series: [{
    values: [64, 59, 55, 49, 39, 35, 31, 20, 16, 15, 9, 5, 4],
    text: "0-18 years"
  }, {
    values: [99, 90, 87, 70, 59, 51, 45, 39, 34, 25, 21, 9, 5],
    text: "18-64 years"
  }, {
    values: [34, 30, 16, 15, 14, 12, 10, 9, 8, 7, 5, 4, 3],
    text: "65 and over"
  }]
}

Summary

Tokens allow dynamically generated text based on some chart value. This allows dynamic labels, styling of tooltips and crosshairs, and rule configuration.