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

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 which 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 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 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 container element. dc.js currently support the following html control elements.

• root.selectAll(".reset") elements is turned on if the chart has an active filter associated with. This control element is 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") element is turned on if the chart has an active filter associated with. The text content of this element is then replaced with the current filter value using the filter printer function set on the chart instance. This element will be turned off automatically if the filter is cleared.