dc.js

Mixin: CoordinateGridMixin

CoordinateGridMixin

Coordinate Grid is an abstract base chart designed to support a number of coordinate grid based concrete chart types, e.g. bar chart, line chart, and bubble chart.

Mixes In:
Source:

Methods

brush( [_])

Get or set the brush. Brush must be an instance of d3 brushes https://github.com/d3/d3-brush/blob/master/README.md You will use this only if you are writing a new chart type that supports brushing.

Caution: dc creates and manages brushes internally. Go through and understand the source code if you want to pass a new brush object. Even if you are only using the getter, the brush object may not behave the way you expect.

Parameters:
Name Type Argument Description
_ d3.brush <optional>
Source:
Returns:
Type
d3.brush | CoordinateGridMixin

brushOn( [brushOn])

Turn on/off the brush-based range filter. When brushing is on then user can drag the mouse across a chart with a quantitative scale to perform range filtering based on the extent of the brush, or click on the bars of an ordinal bar chart or slices of a pie chart to filter and un-filter them. However turning on the brush filter will disable other interactive elements on the chart such as highlighting, tool tips, and reference lines. Zooming will still be possible if enabled, but only via scrolling (panning will be disabled.)

Parameters:
Name Type Argument Default Description
brushOn Boolean <optional>
 true
Source:
Returns:
Type
Boolean | CoordinateGridMixin

chartBodyG( [chartBodyG])

Retrieve the svg group for the chart body.

Parameters:
Name Type Argument Description
chartBodyG SVGElement <optional>
Source:
Returns:
Type
SVGElement

clipPadding( [padding])

Get or set the padding in pixels for the clip path. Once set padding will be applied evenly to the top, left, right, and bottom when the clip path is generated. If set to zero, the clip area will be exactly the chart body area minus the margins.

Parameters:
Name Type Argument Default Description
padding Number <optional>
 5
Source:
Returns:
Type
Number | CoordinateGridMixin

elasticX( [elasticX])

Turn on/off elastic x axis behavior. If x axis elasticity is turned on, then the grid chart will attempt to recalculate the x axis range whenever a redraw event is triggered.

Parameters:
Name Type Argument Default Description
elasticX Boolean <optional>
 false
Source:
Returns:
Type
Boolean | CoordinateGridMixin

elasticY( [elasticY])

Turn on/off elastic y axis behavior. If y axis elasticity is turned on, then the grid chart will attempt to recalculate the y axis range whenever a redraw event is triggered.

Parameters:
Name Type Argument Default Description
elasticY Boolean <optional>
 false
Source:
Returns:
Type
Boolean | CoordinateGridMixin

focus( [range] [, noRaiseEvents])

Zoom this chart to focus on the given range. The given range should be an array containing only 2 elements ([start, end]) defining a range in the x domain. If the range is not given or set to null, then the zoom will be reset. _For focus to work elasticX has to be turned off; otherwise focus will be ignored.

To avoid ping-pong volley of events between a pair of range and focus charts please set noRaiseEvents to true. In that case it will update this chart but will not fire zoom event and not try to update back the associated range chart. If you are calling it manually - typically you will leave it to false (the default).

Parameters:
Name Type Argument Default Description
range Array.<Number> <optional>
noRaiseEvents Boolean <optional>
 false
Source:
Returns:
Type
undefined
Example
chart.on('renderlet', function(chart) {
    // smooth the rendering through event throttling
    events.trigger(function(){
         // focus some other chart to the range selected by user on this chart
         someOtherChart.focus(chart.filter());
    });
})

g( [gElement])

Get or set the root g element. This method is usually used to retrieve the g element in order to overlay custom svg drawing programatically. Caution: The root g element is usually generated by dc.js internals, and resetting it might produce unpredictable result.

Parameters:
Name Type Argument Description
gElement SVGElement <optional>
Source:
Returns:
Type
SVGElement | CoordinateGridMixin

isOrdinal()

Returns true if the chart is using ordinal xUnits (units.ordinal, or false otherwise. Most charts behave differently with ordinal data and use the result of this method to trigger the appropriate logic.

Source:
Returns:
Type
Boolean

mouseZoomable( [mouseZoomable])

Set or get mouse zoom capability flag (default: false). When turned on the chart will be zoomable using the mouse wheel. If the range selector chart is attached zooming will also update the range selection brush on the associated range selector chart.

Parameters:
Name Type Argument Default Description
mouseZoomable Boolean <optional>
 false
Source:
Returns:
Type
Boolean | CoordinateGridMixin

<protected> parentBrushOn( [brushOn])

This will be internally used by composite chart onto children. Please go not invoke directly.

Parameters:
Name Type Argument Default Description
brushOn Boolean <optional>
 false
Source:
Returns:
Type
Boolean | CoordinateGridMixin

rangeChart( [rangeChart])

Get or set the range selection chart associated with this instance. Setting the range selection chart using this function will automatically update its selection brush when the current chart zooms in. In return the given range chart will also automatically attach this chart as its focus chart hence zoom in when range brush updates.

Usually the range and focus charts will share a dimension. The range chart will set the zoom boundaries for the focus chart, so its dimension values must be compatible with the domain of the focus chart.

See the Nasdaq 100 Index example for this effect in action.

Parameters:
Name Type Argument Description
rangeChart CoordinateGridMixin <optional>
Source:
Returns:
Type
CoordinateGridMixin

renderHorizontalGridLines( [renderHorizontalGridLines])

Turn on/off horizontal grid lines.

Parameters:
Name Type Argument Default Description
renderHorizontalGridLines Boolean <optional>
 false
Source:
Returns:
Type
Boolean | CoordinateGridMixin

renderVerticalGridLines( [renderVerticalGridLines])

Turn on/off vertical grid lines.

Parameters:
Name Type Argument Default Description
renderVerticalGridLines Boolean <optional>
 false
Source:
Returns:
Type
Boolean | CoordinateGridMixin

rescale()

When changing the domain of the x or y scale, it is necessary to tell the chart to recalculate and redraw the axes. (.rescale() is called automatically when the x or y scale is replaced with .x() or .y(), and has no effect on elastic scales.)

Source:
Returns:
Type
CoordinateGridMixin

round( [round])

Set or get the rounding function used to quantize the selection when brushing is enabled.

Parameters:
Name Type Argument Description
round function <optional>
Source:
Returns:
Type
function | CoordinateGridMixin
Example
// set x unit round to by month, this will make sure range selection brush will
// select whole months
chart.round(d3.timeMonth.round);

useRightYAxis( [useRightYAxis])

Gets or sets whether the chart should be drawn with a right axis instead of a left axis. When used with a chart in a composite chart, allows both left and right Y axes to be shown on a chart.

Parameters:
Name Type Argument Default Description
useRightYAxis Boolean <optional>
 false
Source:
Returns:
Type
Boolean | CoordinateGridMixin

useTopXAxis( [useTopXAxis])

Gets or sets whether the chart should be drawn with a top axis instead of a bottom axis. When used with a chart in a composite chart, allows both top and bottom X axes to be shown on a chart.

Parameters:
Name Type Argument Default Description
useTopXAxis Boolean <optional>
 false
Source:
Returns:
Type
Boolean | CoordinateGridMixin

x( [xScale])

mandatory

Get or set the x scale. The x scale can be any d3 d3.scale or ordinal scale

Parameters:
Name Type Argument Description
xScale d3.scale <optional>
Source:
See:
Returns:
Type
d3.scale | CoordinateGridMixin
Example
// set x to a linear scale
chart.x(d3.scaleLinear().domain([-2500, 2500]))
// set x to a time scale to generate histogram
chart.x(d3.scaleTime().domain([new Date(1985, 0, 1), new Date(2012, 11, 31)]))

xAxis( [xAxis])

Set or get the x axis used by a particular coordinate grid chart instance. This function is most useful when x axis customization is required. The x axis in dc.js is an instance of a d3 bottom axis object; therefore it supports any valid d3 axisBottom manipulation.

Caution: The x axis is usually generated internally by dc; resetting it may cause unexpected results. Note also that when used as a getter, this function is not chainable: it returns the axis, not the chart, so attempting to call chart functions after calling .xAxis() will fail.

Parameters:
Name Type Argument Default Description
xAxis d3.axis <optional>
 d3.axisBottom()
Source:
See:
Returns:
Type
d3.axis | CoordinateGridMixin
Example
// customize x axis tick format
chart.xAxis().tickFormat(function(v) {return v + '%';});
// customize x axis tick values
chart.xAxis().tickValues([0, 100, 200, 300]);

xAxisLabel( [labelText] [, padding])

Set or get the x axis label. If setting the label, you may optionally include additional padding to the margin to make room for the label. By default the padded is set to 12 to accomodate the text height.

Parameters:
Name Type Argument Default Description
labelText String <optional>
padding Number <optional>
 12
Source:
Returns:
Type
String

xAxisMax()

Calculates the maximum x value to display in the chart. Includes xAxisPadding if set.

Source:
Returns:
Type
*

xAxisMin()

Calculates the minimum x value to display in the chart. Includes xAxisPadding if set.

Source:
Returns:
Type
*

xAxisPadding( [padding])

Set or get x axis padding for the elastic x axis. The padding will be added to both end of the x axis if elasticX is turned on; otherwise it is ignored.

Padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to number or date x axes. When padding a date axis, an integer represents number of units being padded and a percentage string will be treated the same as an integer. The unit will be determined by the xAxisPaddingUnit variable.

Parameters:
Name Type Argument Default Description
padding Number | String <optional>
 0
Source:
Returns:
Type
Number | String | CoordinateGridMixin

xAxisPaddingUnit( [unit])

Set or get x axis padding unit for the elastic x axis. The padding unit will determine which unit to use when applying xAxis padding if elasticX is turned on and if x-axis uses a time dimension; otherwise it is ignored.

The padding unit should be a d3 time interval. For backward compatibility with dc.js 2.0, it can also be the name of a d3 time interval ('day', 'hour', etc). Available arguments are the [d3 time intervals](https://github.com/d3/d3-time/blob/master/README.md#intervals d3.timeInterval).

Parameters:
Name Type Argument Default Description
unit String <optional>
 d3.timeDay
Source:
Returns:
Type
String | CoordinateGridMixin

xUnitCount()

Returns the number of units displayed on the x axis. If the x axis is ordinal (xUnits is units.ordinal), this is the number of items in the domain of the x scale. Otherwise, the x unit count is calculated using the xUnits function.

Source:
Returns:
Type
Number

xUnits( [xUnits])

Set or get the xUnits function. The coordinate grid chart uses the xUnits function to calculate the number of data projections on the x axis such as the number of bars for a bar chart or the number of dots for a line chart.

This function is expected to return a Javascript array of all data points on the x axis, or the number of points on the axis. d3 time range functions d3.timeDays, d3.timeMonths, and d3.timeYears are all valid xUnits functions.

dc.js also provides a few units function, see the Units Namespace for a list of built-in units functions.

Note that as of dc.js 3.0, units.ordinal is not a real function, because it is not possible to define this function compliant with the d3 range functions. It was already a magic value which caused charts to behave differently, and now it is completely so.

Parameters:
Name Type Argument Default Description
xUnits function <optional>
 units.integers
Source:
Returns:
Type
function | CoordinateGridMixin
Example
// set x units to count days
chart.xUnits(d3.timeDays);
// set x units to count months
chart.xUnits(d3.timeMonths);

// A custom xUnits function can be used as long as it follows the following interface:
// units in integer
function(start, end) {
     // simply calculates how many integers in the domain
     return Math.abs(end - start);
}

// fixed units
function(start, end) {
     // be aware using fixed units will disable the focus/zoom ability on the chart
     return 1000;
}

y( [yScale])

Get or set the y scale. The y scale is typically automatically determined by the chart implementation.

Parameters:
Name Type Argument Description
yScale d3.scale <optional>
Source:
See:
Returns:
Type
d3.scale | CoordinateGridMixin

yAxis( [yAxis])

Set or get the y axis used by the coordinate grid chart instance. This function is most useful when y axis customization is required. Depending on useRightYAxis the y axis in dc.js is an instance of either d3.axisLeft or d3.axisRight; therefore it supports any valid d3 axis manipulation.

Caution: The y axis is usually generated internally by dc; resetting it may cause unexpected results. Note also that when used as a getter, this function is not chainable: it returns the axis, not the chart, so attempting to call chart functions after calling .yAxis() will fail. In addition, depending on whether you are going to use the axis on left or right you need to appropriately pass d3.axisLeft or d3.axisRight

Parameters:
Name Type Argument Description
yAxis d3.axisLeft | d3.axisRight <optional>
Source:
See:
Returns:
Type
d3.axisLeft | d3.axisRight | CoordinateGridMixin
Example
// customize y axis tick format
chart.yAxis().tickFormat(function(v) {return v + '%';});
// customize y axis tick values
chart.yAxis().tickValues([0, 100, 200, 300]);

yAxisLabel( [labelText] [, padding])

Set or get the y axis label. If setting the label, you may optionally include additional padding to the margin to make room for the label. By default the padding is set to 12 to accommodate the text height.

Parameters:
Name Type Argument Default Description
labelText String <optional>
padding Number <optional>
 12
Source:
Returns:
Type
String | CoordinateGridMixin

yAxisMax()

Calculates the maximum y value to display in the chart. Includes yAxisPadding if set.

Source:
Returns:
Type
*

yAxisMin()

Calculates the minimum y value to display in the chart. Includes yAxisPadding if set.

Source:
Returns:
Type
*

yAxisPadding( [padding])

Set or get y axis padding for the elastic y axis. The padding will be added to the top and bottom of the y axis if elasticY is turned on; otherwise it is ignored.

Padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to number or date axes. When padding a date axis, an integer represents number of days being padded and a percentage string will be treated the same as an integer.

Parameters:
Name Type Argument Default Description
padding Number | String <optional>
 0
Source:
Returns:
Type
Number | CoordinateGridMixin

zoomOutRestrict( [zoomOutRestrict])

Get or set the zoom restriction for the chart. If true limits the zoom to origional domain of the chart.

Parameters:
Name Type Argument Default Description
zoomOutRestrict Boolean <optional>
 true
Source:
Returns:
Type
Boolean | CoordinateGridMixin

zoomScale( [extent])

Get or set the scale extent for mouse zooms.

Parameters:
Name Type Argument Default Description
extent Array.<(Number|Date)> <optional>
 [1, Infinity]
Source:
Returns:
Type
Array.<(Number|Date)> | CoordinateGridMixin