API Reference

All important functions and modifiers, for you to use crosscompare.js, are listed below. Functions required for usage are listed under Essentials, while mandatory options and settings can be found further down, under Options. Function parameters enclosed in square brackets are optional and can be provided to modify certain behaviour.

Function chaining. Most functions allow them being chained together (i.e. they return the crosscompare instance) and, thus, can be written in the following style (line breaks are optional):

crosscompare.setHeight(200)
.setWidth(300)
.add(chart1)
.add(chart2);

Further APIs. Crosscompare is based upon the JavaScript libraries dc.js and crossfilter, which together form the powerful basis for visually filtering and presenting data. Crosscompare uses the c3.js library for its charts, which - just as dc.js - is built using d3.js. Multiple of those libraries, as well as crosscompare itself, further rely on jQuery. Options, values, and functionality of crosscompare is mostly similar to the underlying libraries. It can, thus, be helpful to look at the respectve APIs for further detail.

Essentials

# crosscompare
.
add(chart, [options])

Via the .add() function is used to register a dc.js chart with crosscompare for later use. Currently, crosscompare has been defined to work with the following dc.js charts: rowChart, pieChart, barChart, lineChart. More dc-chart types may be working, as crosscompare mainly relies on the charts' .group() and .filter() functions, but those have not been tested.

Optionally, certain style settings for rendering a comparison of the provided chart can be defined in form of a JavaScript/JSON object. The following settings can be defined:

anchor: Defines the id of the link/button on which to cache this chart. Default is the dc-chart's anchor with '-cross' appended (e.g. if a dc-chart's anchor is '#my-chart', crosscompare will by default react upon a click on an element with id '#my-chart-cross'). Via the anchor option, one can provide an alternate id for caching the chart.
type: Defines what kind of c3.js chart should be produced to show that chart's comparison. The default chart type is 'line'. Currently, the following c3-chart types are supported:'line', 'line-spline', 'area', 'bar'.
ratio: Only applicable if chart type has been set to 'bar'. Defines the relative width of the single bars within the crosscompare bar chart. Default value is 0.5. Alternatives can range between 0 - 1.
value: Only applicable if the dc-chart's crossfilter group has multiple values (i.e. custom reduce functions). In case there are multiple values to be found, this option must be used to define the 'name' of the key whose values shall be used.
order: Defines if and what ordering should be applied to cached data. Default is 'default'and does not alter the order. Alternatively, 'asc' or 'desc' can be used.
xLabel, yLabel: Defines a label to be displayed at the respective axis. Default is no label.

// Add three dc-charts (which where defined previously)
crosscompare.add(myChart)
.add(otherChart, {type: 'bar', ratio: 0.2, order: 'asc', yLavel: 'y-axis'}) 
.add(anotherChart, {anchor: '#link', value: 'sum'});

# crosscompare
.
render()

This function is not chainable. Upon this function, cached data is being rendered into one comparison graph, displayed within the HTML element with id '#crosscompare' (if no other anchor defined via .setAnchor()).

<!-- Using a link to render crosscompare -->
<a href='javascript:crosscompare.render();'>Render</a>

# crosscompare
.
reset()

This function is not chainable. Upon this function, cached data is being cleared, crosscompare info text is being cleared and the comparison graph is being removed. To only clear crosscompare's cache, but not remove the current comparison graph, use .clear().

<!-- Using a link to reset crosscompare -->
<a href='javascript:crosscompare.reset();'>Reset</a>

Options

# crosscompare
.
addLegend(legend, [title])

Whenever a dc-chart is cached for later comparison, that snapshot of the crossfilter data is being named to destinguish that cache from others. Without any defined legends, crosscompare will not show a legend on the comparison chart. To show and define a legend, this function can be used to pass an id of a HTML selection element or a dc-chart. The legend within the comparison chart will then be labeled according to the values of the selection(s) and/or filters of the chart(s). Additionaly, a title can be provided which will be shown prepended to the legend element.

// Adding a HTML selection element and a graph to crosscompare
crosscompare.addLegend('#my-selection')
.addLegend(myChart, 'Age');

Assuming the selection '#my-selection' had the value 'Men' at the time of caching, and the graph was filtered to ages 18 to 65, then Men Age:18-65 would be shown as the label for that cache. The order of adding the labels to crosscompare, defines the order in which they will be printed within the comparison chart.

# crosscompare
.
setHeight(integer)

Defines the height of the comparison chart. Default height is 200px. Any positive integer can be defined as height. Regardless of default or alternate value, a height must always be defined.

// Set height of comparison chart to 300px
crosscompare.setHeight(300);

# crosscompare
.
setWidth(integer)

Defines the width of the comparison chart. Default width is 'auto', which automatically scales the comparison chart to the width of the superior HTML element. Any positive integer can be defined as width.

// Set width of comparison chart to 600px
crosscompare.setWidth(600);
// Reset width to be automated
crosscompare.setWidth('auto');

# crosscompare
.
setPadding(top, right, bottom, left)

Defines the padding of the comparison chart. Default padding for top, right, bottom, left is 20px, 5px, 10px, 25px, as these values do not waste too much space, nor cut of any axes or labels. Any positive integers can be defined as the paddings. Values for all sides must be provided, even if only one side is being changed.

// Change top padding to 30px
crosscompare.setPadding(30, 5, 10, 25);

# crosscompare
.
setAnchor(string)

Defines the HTML anchor of the element in which the comparison chart will be rendered. Default anchor is '#crosscompare'. Any other HTML id can be provided as a string.

// Change anchor to #my-anchor
crosscompare.setAnchor('#my-anchor');

# crosscompare
.
setDateFormat(string)

Defines the output format of presented dates. The parameter is a string describing the date format with using d3.js' date expressions (e.g. '%H:%M' for just the hours and minutes). Default date format is '%d/%m/%Y'.

// Change the date format to American style
crosscompare.setDateFormat('%m/%d/%Y');

# crosscompare
.
setOverwrite(boolean)

Defines crosscompare's behaviour when two cached states have the same filters applied to them. Default value is false, so that crosscompare will not overwrite the existing cached state, but enumerate the new state and display both. This behaviour can be disabled, so that a state with the same filters as an existing one will overwrite (i.e. update) the original one.

// Enable overwriting/updating cached states (given same filters apply)
crosscompare.setOverwrite(true);

# crosscompare
.
setGrid(boolean, boolean)

Defines whether grid lines will be shown within the comparison chart. First parameter defines behaviour for x-axis lines, second parameter for y-axis lines. By default, both values are set to false, and no grid lines are shown. Values for both axis must be provided, even if only one is being changed.

// Enable y-axis grid lines
crosscompare.setGrid(false, true);

# crosscompare
.
setFlash(boolean)

Defines whether the chart which is being cached is being animated to shortly flash white - indicating that a snapshot of the chart's data has been made. Default is true.

// Disabling the flashing of dc-charts upon caching
crosscompare.setFlash(false);

# crosscompare
.
clear()

This function is not chainable. Upon this function, cached data is being cleared and crosscompare info text is being cleared. The comparison graph is not being removed. To clear crosscompare's cache, as well as the chart, use .reset().

<!-- Using a link to clear crosscompare -->
<a href='javascript:crosscompare.clear();'>Clear</a>