mchart jQuery plug-in

mchart (short for Metrici Chart) is a jQuery plugin that simplifies the creation of charts using front-end JavaScript.

Invoking mchart

The standard Metrici instance invokes mchart for all elements that contain the class mchart, using something like.

$(function() {
  $('.mchart').mchart();
});

The element with mchart on it should contain a table coded in Microformat.

mchart will parse the table options and invoke a chart type according to the value of options.type within the table.

The standard Metrici instance supports four types:

Other Metrici instances may replace these chart types, or offer other chart types.

Registering a new chart type

New chart types can be registed using browser-based scripts.

A new type is registered (or an existing one replaced), using:

(function($){
  $.mchart.register('type',function(chart){
    : chart code goes here
  });
})(jQuery);

The function is passed a chart object, which is described below.

chart object

The chart object contains the following properties:

table

The data passed in the microformat. This will have undergone a number of transformations:

  • The options object, columns array and rows array will be added if they are missing.
  • The table will be converted from secondary format to the primary format if necessary.
  • options.columns values will be applied to the columns, and then options.columns removed.
  • Within options:
    • The axes object will be added if it is missing.
    • An additional columns property will be added to each axis which is an array of the column objects (from table.columns) as specified in the axis column property.
    • The colors object will be added if it is missing. However, color transformation will is not applied to the columns' color properties.

If there are errors interpreting the table data, mchart will show an error.
options A reference to table.options.
element The element which contains the micoformat, after which the chart should be inserted.
container

An empty container inserted after the element which can be replaced with the chart, or into which the chart can be inserted.

The container has a unique id and a class of mchart-container.

The width and height of the container will be set according to options.width and options.height, though chart drivers may choose to override these.
autoWidth Set to true if the width of the container has not been set by the options.
autoHeight Set to true if the height of the container has not been set by the options.

chart methods

The chart object provides the following utility methods:

booleanValue(value [,defaultValue]) Returns the boolean value of v, where v may be a boolean or a string.
color(colorValue) Return a color for a value. This attempts to translate using chart.options.colors. If not found, the value is returned.