Highcharts library

1 Features

To use correctly this engine we suggest you first read carefully the Highcharts' documentation (http://www.highcharts.com); because it offers many settings and options.

The Highcharts library uses a JSON template (see http://www.json.org/ for more details) but you don't need to write it… SpagoBI makes it for you! You need to write a simple xml template by following a few rules, necessary for SpagoBI to translate your settings in JSON format.

Let's see in detail in the next section.

2 Template

To understand better this context we explain you with a simple example.

Suppose you want to get a graph like the following:


2.1 Dataset

All data are getted by a dataset like the next:


2.2 JSON Template

To obtain the previous chart, Highcharts needs a JSON template like this:


2.3 SpagoBI Template

And we - to enable SpagoBI to write the correct template - need to write an XML template like this:


2.3.1 Template's rules

Now, we explain you the few rules to follow for map the xml template in a json template. As you should know, JSON (JavaScript Object Notation) uses two structures:

  • A collection of name/value pairs. In various languages, this is realized as an object. An object is an unordered set of name/value pairs. An object begins with "{" (left brace) and ends with "}" (right brace). Each name is followed by : (colon) and the name/value pairs are separated by , (comma).
  • An ordered list of values. In most languages, this is realized as an array. An array is an ordered collection of values. An array begins with "["(left bracket) and ends with "]" (right bracket). Values are separated by , (comma).
So, told this, we can analyze the two templates and the relative mappings:


Pay attention to these constraints:

  • the first tag for this type of document must be the '' tag.
  • to create a single json object (name:{key:val}), you should write a simple tag xml (). If the name contains un upper case you should put a '_' char in the tag name (before of the lettere that should be in upper case). See the 'X_AXIS' tag that becomes 'xAxis'.
  • to create a json list of values (name: [ {key1:val1},{key2:val2},… ]), you should write a LIST tag. See the SERIES_LIST tag for an example. In this list tag you put the real element name that you want create ('SERIES' in this case that becomes 'series')

2.3.2 Formatters

The engine is able to set different contents on object as tooltips or axis labels BUT isn't able to make calculation on values data. To set the format is necessary put the configuration the formatter property into the template:

<TOOLTIP  backgroundColor='#FCFFC5' crosshairs='true' enabled='true'  shadow='true' formatter='name&#95;percentage'>

The formatter property could be set with next values:

  • name: to view the only name of the serie
  • name_value: to view the serie name and the point value
  • name_percentage: to view the serie name , the point name and the y value followed by the '%' char
  • percentage: to view the serie name and the value followed by the '%' char
  • x_y: to view the x and y value
  • substringLabel: to view the a portion of 10 chars of the label (usefull for the labels of the axis when their value is long)
From SpagoBI 4.2 ...

  • numberFormat( , "" , ""): to view number formatted. It calls the Highcharts.numberFormat function.
  • formatWithNumberRounded: to view the number formatted with unit char (K, M, G, T)
  • abs: to view absolute value number
  • userFunction(): for expert user! It able to pass the body of simple js function. It can be usefull to personalize the content of tooltip, data labels, axis labels. This formatter is in alternative to text property for the tooltip. Pay attention that the < or > char must be converted with the html values.
See below.

<TOOLTIP  backgroundColor='#FCFFC5'  enabled='true' shadow='true' formatter='userFunction("The value for <b>"+ this.point.x + "</b> is <b>"+ this.point.y +"</b>")'>
    <STYLE  color='#4572A7' fontSize='12px' padding='2px' />

This will be:

formatter: function() { return "The value for <b>"+ this.point.x + "</b> is <b>"+ this.point.y +"</b>"; }
<TOOLTIP  backgroundColor='#FCFFC5'  enabled='true' shadow='true' formatter='numberFormat(3,",",".")'>
    <STYLE  color='#4572A7' fontSize='12px' padding='2px' />

  <TOOLTIP  backgroundColor='#FCFFC5'  enabled='true' shadow='true' formatter='formatWithNumberRounded'>
    <STYLE  color='#4572A7' fontSize='12px' padding='2px' />

 <TOOLTIP  backgroundColor='#FCFFC5'  enabled='true' shadow='true' formatter='abs'>
    <STYLE  color='#4572A7' fontSize='12px' padding='2px' />

From SpagoBI 3.4 is possible personalize the tooltip content by using the text property:

<TOOLTIP  backgroundColor='#FCFFC5' crosshairs='true' enabled='true' shadow='true'   text=' $F{...} - {SERIE&#95;NAME} : {SERIE}' >
    <STYLE  color='#4572A7' fontSize='12px' padding='2px' />

In this property is possible reference:

  • a field of the dataset using the $F{..} tag
  • the actual serie name using the {SERIE_NAME} tag
  • the actual serie value using the {SERIE} tag
  • the actual category value using the {CATEGORY} tag

2.3.3 Export

The HC library supports a specific menu with export functionality that for default is hidden because is substituted by the SpagoBI File | Export menu. Anyway is possible activate the original export functionalities setting the EXPORTING property into the template.


  <EXPORTING enabled="true" />

2.3.4 Notes

In addition to the rules dictated by the library Highcharts, SpagoBI expects to receive its configuration in the following form:

  • the SERIES_LIST tag should be always out of the PLOT_OPTIONS tag (see the Examples section). Even if the chart uses a single series.
  • to anchor the fields returned by the dataset to the xy axis, you should set they with the 'alias' tag. For example: <'X_AXIS alias='THE_MONTH' /> . In this case, we are combining the column 'THE_MONTH' returned by the dataset on the x axis. However, to anchor the serie x at the serie y is necessary put both in the alias of the SERIE's tag. It's necessary when you aren't sure of regularity (1:1) between the x and the y values. For example: <'SERIES name="Store sales" alias="THE_MONTH,store_sales" />
  • to view a parameter value on the title or subtitle (usefull with the document composition), you should put its reference in the relative tag definition. For example:
    <TITLE text='Historical of Sales for *$P\{param1\}* ' />
    where 'param1' is the url of a document parameter.
From SpagoBI 3.2 is possible to filter the series by a parameter setting the attribute 'paramFilterSeries' in the CHART property definition:

<CHART type='line' defaultSeriesType='line' paramFilterSeries='url&#95;of&#95;parameter'/>

If you follow these few rules, you are able to create dinamically the most types of charts that the Highcharts library offers .

2.4 Cross Navigation

Like all other SpagoBI documents, is possible to define a cross navigation to other documents or into a composite document.

To activate this feature is necessary add the next piece of configuration into the xml file:

<DRILL document="HIGHCHART&#95;BAR&#95;CROSED">
          <PARAM name='param1' type="ABSOLUTE" value='Gender chart'/>
          <PARAM name="param2" type="CATEGORY"/>
	  <PARAM name="param3" type="SERIE"/>
	  <PARAM name="param4" type="SERIE&#95;NAME"/>
	  <PARAM name="param5" type="RELATIVE"/>

In detail:

  • document: reference the target document label
  • for each parameter is necessary defines the name (url) of the target parameter and the type of it.
The type can assume next values:

  • CATEGORY: pass the category's value selected.
  • SERIE: pass the serie's value selected.
  • SERIE_NAME: pass the serie's name selected.
  • ABSOLUTE: pass the constant defined into the value property.
  • RELATIVE: pass the value of the parameter presents in the request with the name defined in the same property.

3 Examples

SpagoBI offers a variety of widgets' examples realized with the Highcharts library, that can be divided according to the characteristics, in the following categories:

Created by Antonella Giachino on 2011/06/15 17:31
Last modified by Antonella Giachino on 2015/04/09 11:09

This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 2.7.33694 - Documentation