Charts

The versions of charting support described in this page are now deprecated.

Version 4.6.3 introduced support for Apache ECharts, which should be used for new requirements.

Experience has shown that the specific features of different charting libraries are in demand, and that attempting to generalise these is difficult to achieve and inevitably does not fully replicate the features of the libraries.

Our intention is:

  • Support leading open source charting libraries that work well with our data-driven approach, such as Apache Echarts.
  • Reintroduce a small number of simple built-in charting types, which will insulate applications from chart library changes in simple cases.

Metrici supports the creation of charts such as bar graphs and scatter plots.

Charts are produced using browser-based scripts, known as charting drivers. They take their data and options from tables of data that have been written to the page. The tables contain additional markup, known as a Microformat, which allow the scripts to read the data and options.

The microformat recreates the table object that was used to write the table to the page. The table object conforms to a standard Table structure.

The charting driver to use is specified using CSS classes on the table. Charting drivers typically call routines in charting libraries, such as jqPlot or Highcharts, and may use the mchart jQuery plug-in.

See [[charts_2_5_2]] for earlier versions of the charting implementation.

Options

Charts are contolled by setting properties within the table's option block. The following options are used:

cssClass This sets a class on the table which specifies that this is a chart and which charting driver to use.
type The type of chart to show, where this is not specified on the cssClass. The values of this will depend on the chart driver.
showTitle Set to true to show a title for the chart. By default, the title is taken from the table's name property.
title The title to show on the chart. Overrides the name property of the table. Only used if showTitle is true.
width

The width of the chart:

  • "auto" – calculate automatically, typically 100% of the width of the containing element.
  • A number – a width measured in pixels.
height

The height of the chart:

  • "auto" – calculate automatically for the type of chart.
  • A number – a height measured in pixels.
  • A numer followed by % – percentage of the width.

"auto" and the percentage are used to calculate a height in pixels, they are not just passed through as CSS styles.
axes

An object which defines the options for axes. The property names for the object indicate the roles on the chart. For some chart types this is the familiar "xaxis" and "yaxis". In charts that don't naturally have an xaxis and yaxis, other roles are used. For example, a pie chart has "category" and "value" roles.
colors

An object which allows translation of colors. For example, the following translates the colors "red", "amber" and "green":

{
  "red":"#FF0000",
  "amber":"#FFC200",
  "green":"#00FF00"
}

This can be useful when values are read from a column and need to be converted to colours.
showData

Indicates that the element that contains the charting data should be retained on the page, assuming it is visible to start with.
library

Different charting libraries should pass in native options using a property name of their own choosing. Native options should override any options generated by the drivers. The standard mchart types use the jqPlot library, additional options to which can be passed using the jqplot property. The same property name can also be used in other objects such as the axis and column objects, where these correspond to objects in the charting library.

Drivers and chart types may use other properties.

Axis and column properties

Axes define the options for axes on the chart, such as which columns to read the data from and what scale to use.

Column properties define data options such as colour.

The properties of each axis and of the columns depends on the chart driver, but the following are commonly used.

Axis

column

The column that contains the data for the axis.

Can be specified by the 0-based index of the column or the column reference.

Where multiple columns are used, these are passed as an array of index numbers or references.

A one-item array is considered equivalent to passing a single item outside an array.
showLabel

Whether a label should be shown for the axis.
label Label to use for the axis.
min Minimum value.
max Maximum value.
showTicks

Indicates whether ticks should be shown (marks on the axis).
ticks Array of values to use as ticks.
showGridlines

Indicates whether gridlines should be shown (lines across the chart). Default is false.

Gridlines are placed using the ticks values. 

Column properties

showLabel

Whether a label should be shown for the data (in addition to the label for the axis).
name Label to use for the data.
color Color to use for this data. Default is "auto", which means to generate one.

Column properties can be specified using the columns object of the options object, which overrides the properties of the columns themselves.

Data

Data is read from the rows property. See Table structure for more details.

Where non-text data types are expected, drivers can read the text equivalent. So the value "123" is treated the same as 123.

Server-side script

Within a server-side script, you can generate the table together with chart options either as a table with a microformat, or just as a block of JSON. Generating it as a table will ensure that the page will display the data even if the chart is not produced.

Assuming you have:

  • A table in variable table.
  • Options in variable options.
  • Bound scriptTable to Table Script (library.table.TableScript).

Writing out as a table.

application.include('scriptTable');
var html = new Table(table).render(
  Table.extend(options,{microformat:true})
);

The extend is required if the options block does not already contain the microformat option.

As a block of JSON.

application.include('scriptTable');
var html = '<div class="mchart mfJSON">' + 
  application.escape(application.stringify(new Table(table).addOptions(options).applyOptionsColumns().getTable())) +
  '</div>';

In both cases any options.columns are resolved on the server side before writing the table, either by the render() method, or using the applyOptionsColumns() method. Even if options.columns are passed, they are subsequently resolved by the mchart plug-in. Either way, browser-based scripts do not need to process options.columns.

Standard chart types

Metrici supports four basic chart types:

These are specified by using a cssClass of "mchart" and the appropriate chart type as the type property.