API

[Work in Progresss]

The entire dc.js library is scoped under dc name space. It does not introduce anything else into the global name space.

Function Chain

Majority of dc functions are designed to allow function chaining, meaning it will return the current chart instance whenever it is appropriate. Therefore configuration of a chart can be written in the following style.

chart.width(300)
    .height(300)
    .filter("sunday")

The API references will highlight the fact if a particular function is not chainable.

Base Chart [Abstract]

Base chart is an abstract functional object representing a basic dc chart object for all chart and widget implementation. Every function on base chart are also inherited available on all concrete chart implementation in dc library.

.width([value])

Set or get width attribute of a chart. If the value is given, then it will be used as the new width.

If no value specified then value of the current width attribute will be returned.

.height([value])

Set or get height attribute of a chart. If the value is given, then it will be used as the new height.

If no value specified then value of the current height attribute will be returned.

.dimension([value])

Set or get dimension attribute of a chart. In dc a dimension can be any valid crossfilter dimension. If the value is given, then it will be used as the new dimension.

If no value specified then the current dimension will be returned.

.group([value])

Set or get group attribute of a chart. In dc a group is a crossfilter group. Usually the group should be created from the particular dimension associated with the same chart. If the value is given, then it will be used as the new group.

If no value specified then the current group will be returned.

.filterAll()

Clear all filters associated with this chart.

.select(selector)

Execute in scope d3 single selection using the given selector and return d3 selection result. Roughly the same as:

d3.select("#chart-id").select(selector);

This function is not chainable since it does not return a chart instance; however the d3 selection result is chainable from d3's perspective.

.selectAll(selector)

Execute in scope d3 selectAll using the given selector and return d3 selection result. Roughly the same as:

d3.select("#chart-id").selectAll(selector);

This function is not chainable since it does not return a chart instance; however the d3 selection result is chainable from d3's perspective.

.root([rootElement])

Returns the root element where a chart resides. Usually it will be the parent div element where svg was created. You can also pass in a new root element however this is usually handled as part of the dc internal. Resetting root element on a chart outside of dc internal might have unexpected consequences.

.svg([svgElement])

Returns the top svg element for this specific chart. You can also pass in a new svg element however this is usually handled as part of the dc internal. Resetting svg element on a chart outside of dc internal might have unexpected consequences.

.filterPrinter([filterPrinterFunction])

Set or get filter printer function. Filter printer function is used to generate human friendly text for filter value(s) associated with the chart instance. By default dc charts shipped with a default filter printer implementation dc.printers.filter that provides simple printing support for both single value and ranged filters.

.turnOnControls() & .turnOffControls

Turn on/off optional control elements within the root element. dc.js currently support the following html control elements.

• root.selectAll(".reset") elements are turned on if the chart has an active filter. This type of control elements are usually used to store reset link to allow user to reset filter on a certain chart. This element will be turned off automatically if the filter is cleared.
• root.selectAll(".filter") elements are turned on if the chart has an active filter. The text content of this element is then replaced with the current filter value using the filter printer function. This type of element will be turned off automatically if the filter is cleared.

.transitionDuration([duration])

Set or get animation transition duration(in milliseconds) for specific chart instance. Default duration is 750ms.

Color Chart [Abstract]

Color chart is an abstract chart object created to provide universal coloring support as a mix-in.

.colors([colorScale or colorArray])

Retrieve current color scale or set a new color scale. This function accepts both d3 color scale and arbitrary color array. By default d3.scale.category20c() is used.

// colors example
chart.colors(d3.scale.category20b());
chart.colors(["#a60000","#ff0000", "#ff4040","#ff7373","#67e667","#39e639","#00cc00"]);

.colorAccessor([colorAccessorFunction])

Set or get color accessor function. This function will be used to map a data point on crossfilter group to a specific color value on the color scale. Default implementation of this function simply returns the next color on the scale using the index of a group.

// default index based color accessor
.colorAccessor(function(d, i){return i;})
// color accessor for a multi-value crossfilter reduction
.colorAccessor(function(d){return d.value.absGain;})