dc.js

Mixin: BaseMixin

BaseMixin

BaseMixin is an abstract functional object representing a basic dc chart object for all chart and widget implementations. Methods from the BaseMixin are inherited and available on all chart implementations in the dc library.

Source:

Methods

addFilterHandler( [addFilterHandler])

Set or get the add filter handler. The add filter handler is a function that adds a filter to the chart's filter list. Using a custom add filter handler allows you to change the way filters are added or perform additional work when adding a filter, e.g. when using a filter server other than crossfilter.

The handler should return a new or modified array as the result.

Parameters:
Name Type Argument Description
addFilterHandler function <optional>
Source:
Returns:
Type
function | BaseMixin
Example
// default add filter handler
chart.addFilterHandler(function (filters, filter) {
    filters.push(filter);
    return filters;
});

// custom filter handler (no-op)
chart.addFilterHandler(function(filters, filter) {
    return filters;
});

anchor( [parent] [, chartGroup])

Set the root SVGElement to either be an existing chart's root; or any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection. Optionally registers the chart within the chartGroup. This class is called internally on chart initialization, but be called again to relocate the chart. However, it will orphan any previously created SVGElements.

Parameters:
Name Type Argument Description
parent anchorChart | anchorSelector | anchorNode <optional>
chartGroup String <optional>
Source:
Returns:
Type
String | node | d3.selection | BaseMixin

anchorName()

Returns the DOM id for the chart's anchored location.

Source:
Returns:
Type
String

chartGroup( [chartGroup])

Get or set the chart group to which this chart belongs. Chart groups are rendered or redrawn together since it is expected they share the same underlying crossfilter data set.

Parameters:
Name Type Argument Description
chartGroup String <optional>
Source:
Returns:
Type
String | BaseMixin

chartID()

Returns the internal numeric ID of the chart.

Source:
Returns:
Type
String

commitHandler(commitHandler)

Gets/sets the commit handler. If the chart has a commit handler, the handler will be called when the chart's filters have changed, in order to send the filter data asynchronously to a server.

Unlike other functions in dc.js, the commit handler is asynchronous. It takes two arguments: a flag indicating whether this is a render (true) or a redraw (false), and a callback to be triggered once the commit is done. The callback has the standard node.js continuation signature with error first and result second.

Parameters:
Name Type Description
commitHandler function
Source:
Returns:
Type
BaseMixin

controlsUseVisibility( [controlsUseVisibility])

If set, use the visibility attribute instead of the display attribute for showing/hiding chart reset and filter controls, for less disruption to the layout.

Parameters:
Name Type Argument Default Description
controlsUseVisibility Boolean <optional>
 false
Source:
Returns:
Type
Boolean | BaseMixin

data( [callback])

Set the data callback or retrieve the chart's data set. The data callback is passed the chart's group and by default will return group.all. This behavior may be modified to, for instance, return only the top 5 groups.

Parameters:
Name Type Argument Description
callback function <optional>
Source:
Returns:
Type
* | BaseMixin
Example
// Default data function
chart.data(function (group) { return group.all(); });

chart.data(function (group) { return group.top(5); });

dimension( [dimension])

mandatory

Set or get the dimension attribute of a chart. In dc, a dimension can be any valid crossfilter dimension

If a value is given, then it will be used as the new dimension. If no value is specified then the current dimension will be returned.

Parameters:
Name Type Argument Description
dimension crossfilter.dimension <optional>
Source:
See:
Returns:
Type
crossfilter.dimension | BaseMixin
Example
var index = crossfilter([]);
var dimension = index.dimension(pluck('key'));
chart.dimension(dimension);

expireCache()

Expire the internal chart cache. dc charts cache some data internally on a per chart basis to speed up rendering and avoid unnecessary calculation; however it might be useful to clear the cache if you have changed state which will affect rendering. For example, if you invoke crossfilter.add function or reset group or dimension after rendering, it is a good idea to clear the cache to make sure charts are rendered properly.

Source:
Returns:
Type
BaseMixin

filter( [filter])

Filter the chart by the given parameter, or return the current filter if no input parameter is given.

The filter parameter can take one of these forms:

Note that this is always a toggle (even when it doesn't make sense for the filter type). If you wish to replace the current filter, either call chart.filter(null) first - or it's more efficient to call chart.replaceFilter(filter) instead.

Each toggle is executed by checking if the value is already present using the hasFilterHandler; if it is not present, it is added using the addFilterHandler; if it is already present, it is removed using the removeFilterHandler.

Once the filters array has been updated, the filters are applied to the crossfilter dimension, using the filterHandler.

Once you have set the filters, call chart.redrawGroup() (or redrawAll()) to redraw the chart's group.

Parameters:
Name Type Argument Description
filter * <optional>
Source:
See:
Returns:
Type
BaseMixin
Example
// filter by a single string
chart.filter('Sunday');
// filter by a single age
chart.filter(18);
// filter by a set of states
chart.filter([['MA', 'TX', 'ND', 'WA']]);
// filter by range -- note the use of filters.RangedFilter, which is different
// from the syntax for filtering a crossfilter dimension directly, dimension.filter([15,20])
chart.filter(filters.RangedFilter(15,20));

filterAll()

Clear all filters associated with this chart. The same effect can be achieved by calling chart.filter(null).

Source:
Returns:
Type
BaseMixin

filterHandler( [filterHandler])

Set or get the filter handler. The filter handler is a function that performs the filter action on a specific dimension. Using a custom filter handler allows you to perform additional logic before or after filtering.

Parameters:
Name Type Argument Description
filterHandler function <optional>
Source:
See:
Returns:
Type
function | BaseMixin
Example
// the default filter handler handles all possible cases for the charts in dc.js
// you can replace it with something more specialized for your own chart
chart.filterHandler(function (dimension, filters) {
    if (filters.length === 0) {
        // the empty case (no filtering)
        dimension.filter(null);
    } else if (filters.length === 1 && !filters[0].isFiltered) {
        // single value and not a function-based filter
        dimension.filterExact(filters[0]);
    } else if (filters.length === 1 && filters[0].filterType === 'RangedFilter') {
        // single range-based filter
        dimension.filterRange(filters[0]);
    } else {
        // an array of values, or an array of filter objects
        dimension.filterFunction(function (d) {
            for (var i = 0; i < filters.length; i++) {
                var filter = filters[i];
                if (filter.isFiltered && filter.isFiltered(d)) {
                    return true;
                } else if (filter <= d && filter >= d) {
                    return true;
                }
            }
            return false;
        });
    }
    return filters;
});

// custom filter handler
chart.filterHandler(function(dimension, filter){
    var newFilter = filter + 10;
    dimension.filter(newFilter);
    return newFilter; // set the actual filter value to the new value
});

filterPrinter( [filterPrinterFunction])

Set or get the filter printer function. The filter printer function is used to generate human friendly text for filter value(s) associated with the chart instance. The text will get shown in the `.filter element; see turnOnControls.

By default dc charts use a default filter printer printers.filters that provides simple printing support for both single value and ranged filters.

Parameters:
Name Type Argument Default Description
filterPrinterFunction function <optional>
 printers.filters
Source:
Returns:
Type
function | BaseMixin
Example
// for a chart with an ordinal brush, print the filters in upper case
chart.filterPrinter(function(filters) {
  return filters.map(function(f) { return f.toUpperCase(); }).join(', ');
});
// for a chart with a range brush, print the filter as start and extent
chart.filterPrinter(function(filters) {
  return 'start ' + utils.printSingleValue(filters[0][0]) +
    ' extent ' + utils.printSingleValue(filters[0][1] - filters[0][0]);
});

filters()

Returns all current filters. This method does not perform defensive cloning of the internal filter array before returning, therefore any modification of the returned array will effect the chart's internal filter storage.

Source:
Returns:
Type
Array.<*>

group( [group] [, name])

mandatory

Set or get the 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 a value is given, then it will be used as the new group.

If no value specified then the current group will be returned. If name is specified then it will be used to generate legend label.

Parameters:
Name Type Argument Description
group crossfilter.group <optional>
name String <optional>
Source:
See:
Returns:
Type
crossfilter.group | BaseMixin
Example
var index = crossfilter([]);
var dimension = index.dimension(pluck('key'));
chart.dimension(dimension);
chart.group(dimension.group().reduceSum());

hasFilter( [filter])

Check whether any active filter or a specific filter is associated with particular chart instance. This function is not chainable.

Parameters:
Name Type Argument Description
filter * <optional>
Source:
See:
Returns:
Type
Boolean

hasFilterHandler( [hasFilterHandler])

Set or get the has-filter handler. The has-filter handler is a function that checks to see if the chart's current filters (first argument) include a specific filter (second argument). Using a custom has-filter handler allows you to change the way filters are checked for and replaced.

Parameters:
Name Type Argument Description
hasFilterHandler function <optional>
Source:
Returns:
Type
function | BaseMixin
Example
// default has-filter handler
chart.hasFilterHandler(function (filters, filter) {
    if (filter === null || typeof(filter) === 'undefined') {
        return filters.length > 0;
    }
    return filters.some(function (f) {
        return filter <= f && filter >= f;
    });
});

// custom filter handler (no-op)
chart.hasFilterHandler(function(filters, filter) {
    return false;
});

height( [height])

Set or get the height attribute of a chart. The height is applied to the SVGElement generated by the chart when rendered (or re-rendered). If a value is given, then it will be used to calculate the new height and the chart returned for method chaining. The value can either be a numeric, a function, or falsy. If no value is specified then the value of the current height attribute will be returned.

By default, without an explicit height being given, the chart will select the width of its anchor element. If that isn't possible it defaults to 200 (provided by the minHeight property). Setting the value falsy will return the chart to the default behavior.

Parameters:
Name Type Argument Description
height Number | function <optional>
Source:
See:
Returns:
Type
Number | BaseMixin
Example
// Default height
chart.height(function (element) {
    var height = element && element.getBoundingClientRect && element.getBoundingClientRect().height;
    return (height && height > chart.minHeight()) ? height : chart.minHeight();
});

chart.height(250); // Set the chart's height to 250px;
chart.height(function(anchor) { return doSomethingWith(anchor); }); // set the chart's height with a function
chart.height(null); // reset the height to the default auto calculation

keyAccessor( [keyAccessor])

Set or get the key accessor function. The key accessor function is used to retrieve the key value from the crossfilter group. Key values are used differently in different charts, for example keys correspond to slices in a pie chart and x axis positions in a grid coordinate chart.

Parameters:
Name Type Argument Description
keyAccessor function <optional>
Source:
Returns:
Type
function | BaseMixin
Example
// default key accessor
chart.keyAccessor(function(d) { return d.key; });
// custom key accessor for a multi-value crossfilter reduction
chart.keyAccessor(function(p) { return p.value.absGain; });

keyboardAccessible( [keyboardAccessible])

If set, interactive chart elements like individual bars in a bar chart or symbols in a scatter plot will be focusable from keyboard and on pressing Enter or Space will behave as if clicked on.

If svgDescription has not been explicitly set, will also set SVG description text to the class constructor name, like BarChart or HeatMap, and make the entire SVG focusable.

Parameters:
Name Type Argument Default Description
keyboardAccessible Boolean <optional>
 false
Source:
Returns:
Type
Boolean | BarChart

label( [labelFunction] [, enableLabels])

Set or get the label function. The chart class will use this function to render labels for each child element in the chart, e.g. slices in a pie chart or bubbles in a bubble chart. Not every chart supports the label function, for example line chart does not use this function at all. By default, enables labels; pass false for the second parameter if this is not desired.

Parameters:
Name Type Argument Default Description
labelFunction function <optional>
enableLabels Boolean <optional>
 true
Source:
Returns:
Type
function | BaseMixin
Example
// default label function just return the key
chart.label(function(d) { return d.key; });
// label function has access to the standard d3 data binding and can get quite complicated
chart.label(function(d) { return d.data.key + '(' + Math.floor(d.data.value / all.value() * 100) + '%)'; });

legend( [legend])

Attach a Legend widget to this chart. The legend widget will automatically draw legend labels based on the color setting and names associated with each group.

Parameters:
Name Type Argument Description
legend Legend <optional>
Source:
Returns:
Type
Legend | BaseMixin
Example
chart.legend(new Legend().x(400).y(10).itemHeight(13).gap(5))

minHeight( [minHeight])

Set or get the minimum height attribute of a chart. This only has effect when used with the default height function.

Parameters:
Name Type Argument Default Description
minHeight Number <optional>
 200
Source:
See:
Returns:
Type
Number | BaseMixin

minWidth( [minWidth])

Set or get the minimum width attribute of a chart. This only has effect when used with the default width function.

Parameters:
Name Type Argument Default Description
minWidth Number <optional>
 200
Source:
See:
Returns:
Type
Number | BaseMixin

on(event, listener)

All dc chart instance supports the following listeners. Supports the following events:

  • renderlet - This listener function will be invoked after transitions after redraw and render. Replaces the deprecated renderlet method.
  • pretransition - Like .on('renderlet', ...) but the event is fired before transitions start.
  • preRender - This listener function will be invoked before chart rendering.
  • postRender - This listener function will be invoked after chart finish rendering including all renderlets' logic.
  • preRedraw - This listener function will be invoked before chart redrawing.
  • postRedraw - This listener function will be invoked after chart finish redrawing including all renderlets' logic.
  • filtered - This listener function will be invoked after a filter is applied, added or removed.
  • zoomed - This listener function will be invoked after a zoom is triggered.
Parameters:
Name Type Description
event String
listener function
Source:
See:
Returns:
Type
BaseMixin
Example
.on('renderlet', function(chart, filter){...})
.on('pretransition', function(chart, filter){...})
.on('preRender', function(chart){...})
.on('postRender', function(chart){...})
.on('preRedraw', function(chart){...})
.on('postRedraw', function(chart){...})
.on('filtered', function(chart, filter){...})
.on('zoomed', function(chart, filter){...})

onClick(datum)

This function is passed to d3 as the onClick handler for each chart. The default behavior is to filter on the clicked datum (passed to the callback) and redraw the chart group.

This function can be replaced in order to change the click behavior (but first look at

Parameters:
Name Type Description
datum *
Source:
Returns:
Type
undefined
Example
var oldHandler = chart.onClick;
chart.onClick = function(datum) {
  // use datum.

options(opts)

Set chart options using a configuration object. Each key in the object will cause the method of the same name to be called with the value to set that attribute for the chart.

Parameters:
Name Type Description
opts Object
Source:
Returns:
Type
BaseMixin
Example
chart.options({dimension: myDimension, group: myGroup});

ordering( [orderFunction])

Get or set an accessor to order ordinal dimensions. The chart uses Array.sort to sort elements; this accessor returns the value to order on.

Parameters:
Name Type Argument Description
orderFunction function <optional>
Source:
Returns:
Type
function | BaseMixin
Example
// Default ordering accessor
_chart.ordering(pluck('key'));

redraw()

Calling redraw will cause the chart to re-render data changes incrementally. If there is no change in the underlying data dimension then calling this method will have no effect on the chart. Most chart interaction in dc will automatically trigger this method through internal events (in particular redrawAll); therefore, you only need to manually invoke this function if data is manipulated outside of dc's control (for example if data is loaded in the background using crossfilter.add).

Source:
Returns:
Type
BaseMixin

redrawGroup()

Redraws all charts in the same group as this chart, typically in reaction to a filter change. If the chart has a commitHandler, it will be executed and waited for.

Source:
Returns:
Type
BaseMixin

removeFilterHandler( [removeFilterHandler])

Set or get the remove filter handler. The remove filter handler is a function that removes a filter from the chart's current filters. Using a custom remove filter handler allows you to change how filters are removed or perform additional work when removing a filter, e.g. when using a filter server other than crossfilter.

The handler should return a new or modified array as the result.

Parameters:
Name Type Argument Description
removeFilterHandler function <optional>
Source:
Returns:
Type
function | BaseMixin
Example
// default remove filter handler
chart.removeFilterHandler(function (filters, filter) {
    for (var i = 0; i < filters.length; i++) {
        if (filters[i] <= filter && filters[i] >= filter) {
            filters.splice(i, 1);
            break;
        }
    }
    return filters;
});

// custom filter handler (no-op)
chart.removeFilterHandler(function(filters, filter) {
    return filters;
});

render()

Invoking this method will force the chart to re-render everything from scratch. Generally it should only be used to render the chart for the first time on the page or if you want to make sure everything is redrawn from scratch instead of relying on the default incremental redrawing behaviour.

Source:
Returns:
Type
BaseMixin

renderGroup()

Renders all charts in the same group as this chart. If the chart has a commitHandler, it will be executed and waited for

Source:
Returns:
Type
BaseMixin

renderLabel( [renderLabel])

Turn on/off label rendering

Parameters:
Name Type Argument Default Description
renderLabel Boolean <optional>
 false
Source:
Returns:
Type
Boolean | BaseMixin

renderlet(renderletFunction)

A renderlet is similar to an event listener on rendering event. Multiple renderlets can be added to an individual chart. Each time a chart is rerendered or redrawn the renderlets are invoked right after the chart finishes its transitions, giving you a way to modify the SVGElements. Renderlet functions take the chart instance as the only input parameter and you can use the dc API or use raw d3 to achieve pretty much any effect.

Use on with a 'renderlet' prefix. Generates a random key for the renderlet, which makes it hard to remove.

Parameters:
Name Type Description
renderletFunction function
Deprecated:
  • chart.renderlet has been deprecated. Please use chart.on("renderlet.", renderletFunction)
Source:
Returns:
Type
BaseMixin
Example
// do this instead of .renderlet(function(chart) { ... })
chart.on("renderlet", function(chart){
    // mix of dc API and d3 manipulation
    chart.select('g.y').style('display', 'none');
    // its a closure so you can also access other chart variable available in the closure scope
    moveChart.filter(chart.filter());
});

renderTitle( [renderTitle])

Turn on/off title rendering, or return the state of the render title flag if no arguments are given.

Parameters:
Name Type Argument Default Description
renderTitle Boolean <optional>
 true
Source:
Returns:
Type
Boolean | BaseMixin

replaceFilter( [filter])

Replace the chart filter. This is equivalent to calling chart.filter(null).filter(filter) but more efficient because the filter is only applied once.

Parameters:
Name Type Argument Description
filter * <optional>
Source:
Returns:
Type
BaseMixin

resetFilterHandler( [resetFilterHandler])

Set or get the reset filter handler. The reset filter handler is a function that resets the chart's filter list by returning a new list. Using a custom reset filter handler allows you to change the way filters are reset, or perform additional work when resetting the filters, e.g. when using a filter server other than crossfilter.

The handler should return a new or modified array as the result.

Parameters:
Name Type Argument Description
resetFilterHandler function <optional>
Source:
Returns:
Type
BaseMixin
Example
// default remove filter handler
function (filters) {
    return [];
}

// custom filter handler (no-op)
chart.resetFilterHandler(function(filters) {
    return filters;
});

resetSvg()

Remove the chart's SVGElements from the dom and recreate the container SVGElement.

Source:
See:
Returns:
Type
SVGElement

root( [rootElement])

Returns the root element where a chart resides. Usually it will be the parent div element where the SVGElement was created. You can also pass in a new root element however this is usually handled by dc internally. Resetting the root element on a chart outside of dc internals may have unexpected consequences.

Parameters:
Name Type Argument Description
rootElement HTMLElement <optional>
Source:
See:
Returns:
Type
HTMLElement | BaseMixin

select(sel)

Execute d3 single selection in the chart's scope using the given selector and return the d3 selection.

This function is not chainable since it does not return a chart instance; however the d3 selection result can be chained to d3 function calls.

Parameters:
Name Type Description
sel String

CSS selector string
Source:
See:
Returns:
Type
d3.selection
Example
// Has the same effect as d3.select('#chart-id').select(selector)
chart.select(selector)

selectAll(sel)

Execute in scope d3 selectAll using the given selector and return d3 selection result.

This function is not chainable since it does not return a chart instance; however the d3 selection result can be chained to d3 function calls.

Parameters:
Name Type Description
sel String

CSS selector string
Source:
See:
Returns:
Type
d3.selection
Example
// Has the same effect as d3.select('#chart-id').selectAll(selector)
chart.selectAll(selector)

svg( [svgElement])

Returns the top SVGElement for this specific chart. You can also pass in a new SVGElement, however this is usually handled by dc internally. Resetting the SVGElement on a chart outside of dc internals may have unexpected consequences.

Parameters:
Name Type Argument Description
svgElement SVGElement | d3.selection <optional>
Source:
See:
Returns:
Type
SVGElement | d3.selection | BaseMixin

svgDescription( [description])

Set or get description text for the entire SVG graphic. If set, will create a <desc> element as the first child of the SVG with the description text and also make the SVG focusable from keyboard.

Parameters:
Name Type Argument Description
description String <optional>
Source:
Returns:
Type
String | BaseMixin

title( [titleFunction])

Set or get the title function. The chart class will use this function to render the SVGElement title (usually interpreted by browser as tooltips) for each child element in the chart, e.g. a slice in a pie chart or a bubble in a bubble chart. Almost every chart supports the title function; however in grid coordinate charts you need to turn off the brush in order to see titles, because otherwise the brush layer will block tooltip triggering.

Parameters:
Name Type Argument Description
titleFunction function <optional>
Source:
Returns:
Type
function | BaseMixin
Example
// default title function shows "key: value"
chart.title(function(d) { return d.key + ': ' + d.value; });
// title function has access to the standard d3 data binding and can get quite complicated
chart.title(function(p) {
   return p.key.getFullYear()
       + '\n'
       + 'Index Gain: ' + numberFormat(p.value.absGain) + '\n'
       + 'Index Gain in Percentage: ' + numberFormat(p.value.percentageGain) + '%\n'
       + 'Fluctuation / Index Ratio: ' + numberFormat(p.value.fluctuationPercentage) + '%';
});

transitionDelay( [delay])

Set or get the animation transition delay (in milliseconds) for this chart instance.

Parameters:
Name Type Argument Default Description
delay Number <optional>
 0
Source:
Returns:
Type
Number | BaseMixin

transitionDuration( [duration])

Set or get the animation transition duration (in milliseconds) for this chart instance.

Parameters:
Name Type Argument Default Description
duration Number <optional>
 750
Source:
Returns:
Type
Number | BaseMixin

turnOffControls()

Turn off optional control elements within the root element.

Source:
See:
Returns:
Type
BaseMixin

turnOnControls()

Turn on optional control elements within the root element. dc currently supports the following html control elements.

  • root.selectAll('.reset') - elements are turned on if the chart has an active filter. This type of control element is usually used to store a 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.
Source:
Returns:
Type
BaseMixin

useViewBoxResizing( [useViewBoxResizing])

Turn on/off using the SVG viewBox attribute. When enabled, viewBox will be set on the svg root element instead of width and height. Requires that the chart aspect ratio be defined using chart.width(w) and chart.height(h).

This will maintain the aspect ratio while enabling the chart to resize responsively to the space given to the chart using CSS. For example, the chart can use width: 100%; height: 100% or absolute positioning to resize to its parent div.

Since the text will be sized as if the chart is drawn according to the width and height, and will be resized if the chart is any other size, you need to set the chart width and height so that the text looks good. In practice, 600x400 seems to work pretty well for most charts.

You can see examples of this resizing strategy in the Chart Resizing Examples; just add ?resize=viewbox to any of the one-chart examples to enable useViewBoxResizing.

Parameters:
Name Type Argument Default Description
useViewBoxResizing Boolean <optional>
 false
Source:
Returns:
Type
Boolean | BaseMixin

valueAccessor( [valueAccessor])

Set or get the value accessor function. The value accessor function is used to retrieve the value from the crossfilter group. Group values are used differently in different charts, for example values correspond to slice sizes in a pie chart and y axis positions in a grid coordinate chart.

Parameters:
Name Type Argument Description
valueAccessor function <optional>
Source:
Returns:
Type
function | BaseMixin
Example
// default value accessor
chart.valueAccessor(function(d) { return d.value; });
// custom value accessor for a multi-value crossfilter reduction
chart.valueAccessor(function(p) { return p.value.percentageGain; });

width( [width])

Set or get the width attribute of a chart.

Parameters:
Name Type Argument Description
width Number | function <optional>
Source:
See:
Returns:
Type
Number | BaseMixin
Example
// Default width
chart.width(function (element) {
    var width = element && element.getBoundingClientRect && element.getBoundingClientRect().width;
    return (width && width > chart.minWidth()) ? width : chart.minWidth();
});