DC.js - baseMixin

baseMixin provides basic methods needed to create any type of a chart. It ranges from setting the width of the chart to advanced filtering of the chart.

General Chart Options

The basicMixin provides many chart methods to get / set the properties of the charts. They are as follows,

  • chartID() − Returns the internal numeric ID of the chart.

  • chartGroup( [chartGroup]) − Gets or sets the group to which the chart belongs. In DC.js, charts can be grouped into a single set. All charts in a group are expected to share the same Crossfilter dataset. They are rendered as well as redrawn simultaneously.

mychart.chartGroup('dashboard');

  • minWidth( [minWidth]) − Sets the minimum width of the chart.

mychart.minWidth(300);

  • width( [width]) − Gets or sets the width of the chart.

mychart.width(600);

  • minHeight( [minHeight]) − Gets or sets the minimum height of the chart.

mychart.minHeight(300);

  • height( [height]) − Gets or sets the height of the chart.

mychart.height(300);

  • title( [titleFunction]) − Gets or sets the title function. Title is the SVG Element's title of the child element in the chart (e.g. a single bar in a bar chart). Title in the charts are represented as tooltip in the browser.

mychart.title(function(data) { 
   return d.key + ': ' + d.value; 
});

  • label( labelFunction[??]) − Similar to the title() method, but it sets the label instead of the title.

mychart.label(function(data) { 
   return d.key + ': ' + d.value; 
});

  • options(opts) − Sets any chart option using the JavaScript object. Each key represents the corresponding method available in the charts and the matched method will be invoked with the relevant value.

mychart.options ({
   'width' : 300,
   'height' : 300
});

Here, width() and height() method will be fired with the specified value.

  • legend( [legend]) − Attaches a legend to the chart. The legend can be created using the d3.legend() method.

mychart.legend (
   dc.legend()
      .x(500)
      .y(50)
      .itemHeight(12)
      .gap(4))

  • anchor( parent[??]) − Sets the root SVGElement to be either an existing chart's root or any valid D3 single selectors. Optionally, the chart group can also be set using the second argument.

  • anchorName() − Gets the DOM ID of the chart's anchored location.

  • svg( [svgElement]) − Returns the SVGElement of the chart.

  • resetSvg() − Resets the SVG container in the DOM.

  • root( [rootElement]) − Gets the root container of the chart.

Data Options

basicMixin provides methods to set the data for the charts. The data is set as Crossfilter dimension and group. In addition, it provides an option to get the underlying dataset.

  • dimension( [dimension]) − Sets or gets the dimension of the chart. A dimension is any valid Crossfilter dimension.

var mycrossfilter = crossfilter([]);
var ageDimension = mycrossfilter.dimension(dc.pluck('age'));
mychart.dimension(ageDimension);

  • group( group[??]) − Sets or gets the group of the chart. A group is any valid Crossfilter group. The group can be named using the second argument to use it later in the code.

var mycrossfilter = crossfilter([]);
var ageDimension = mycrossfilter.dimension(dc.pluck('age'));
mychart.dimension(ageDimension);
mychart.group(ageDimension.group(crossfilter.reduceCount()));

  • data( [callback]) − Sets the data callback and enables us to get the underlying chart's data set.

// get all groups
mychart.data(function (group) { 
   return group.all(); 
});

// get top five groups
mychart.data(function (group) { 
   return group.top(5); 
});

  • keyAccessor( [keyAccessor]) − Gets or sets the key accessor function. It is used to retrieve the key from the underlying Crossfilter group. The key is used for slices in a pie chart and x-axis in the line / bar chart. The default key accessor function is as follows −

chart.keyAccessor(function(d) { return d.key; });

  • valueAccessor( [valueAccessor]) − Gets or sets the value accessor function. It is used to retrieve the value from the underlying Crossfilter group. The value is used for slice size in the pie chart and y-axis position in the line / bar chart. The default value accessor function is as follows −

chart.valueAccessor(function(d) { return d.value; });

  • ordering( [orderFunction]) − Gets or sets an ordering function to order ordinal dimension. By default, a chart uses crossfilter.quicksort.by to sort the elements.

_chart.ordering(dc.pluck('key'));

Filter Options

Filtering is one of the highlights of DC.js. We can apply one or more filters directly on the chart object using the filter() method and call chart's redrawGroup() or dc.redrawAll() method to see the filtering effect on the chart. By default, a chart object takes one or more filters using the filter() method, applies it on the underlying Crossfilter() data set, gets the filtered data from the Crossfilter and redraws the charts using the filtered data. DC.js provides the following methods to handle filtering in the chart.

Filter( [filter])

Gets or sets the filter for the chart. If a supplied filter is new, then it will be added to the chart's filter collection and applied on the underlying dataset. If the filter supplied is already available in the chart's filter collection, then it will remove the filter and do the relevant filtering on the underlying data. In short, filter method will toggle the supplied filters.

mychart.filter(10);

To remove all filters, call the filter method with null value. The filter may be any one of the following items −

  • null − Chart will remove all the filters previously applied.

  • single value − Chart will call the underlying Crossfilter's filter method and send the supplied value.

  • dc.filters.RangedFilter − It accepts two values, low and high. Chart will filter out all the data, except the value in the range between low and high value.

  • dc.filters.TwoDimensionalFilter − It accepts two-dimensional values that are used in the heat map.

  • dc.filters.RangedTwoDimensionalFilter − It is similar to the dc.filters.RangedFilter, except that it accepts a two-dimensional value only used in scatter plots.

hasFilter( [filter])

Checks whether the supplied filter is available or not in the chart.

replaceFilter( [filter])

Replaces the current filter of the chart with the supplied filter.

filters()

Returns all current filters associated with the chart.

filterAll()

Clears all filters associated with the chart.

filterHandler( [filterHandler])

Gets or sets a filter handler function. Filter handler function is used by the chart to filter the underlying dataset using the filter. Chart has a Default Filter Handler Function and it can be replaced by a Custom Filter Handler Function using this method. The default filter handler is as follows −

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;
});

hasFilterHandler( [hasFilterHandler])

Gets or sets a has-filter handler function. This function is used by the chart to check whether a filter is available in the chart's filter collection or not. The default has-filter handler is as follows −

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;
   });
});

addFilterHandler( [addFilterHandler])

Gets or sets the add-filter handler function. This function is used by the chart to add the filter into the chart's filter collection. The default add-filter handler is as follows −

chart.addFilterHandler(function (filters, filter) {
   filters.push(filter);
   return filters;
});

removeFilterHandler( [removeFilterHandler])

Gets or sets the remove-filter handler function. This function is used by the chart to remove the filter from the chart's filter collection. The default remove-filter is as follows −

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;
});

resetFilterHandler( [resetFilterHandler])

Gets or sets the reset-filter handler function. This function is used by the chart to reset the chart's filter collection. The default reset-filter is as follows −

function (filters) {
   return [];
}

filterPrinter( [filterPrinterFunction])

Gets or sets the printer-filter function. This function is used by the chart to print the filter information.

commitHandler()

Gets or sets the commit handler. The purpose of the commit handler is to send the filtered data to the server asynchronously.

Event Options

DC.js defines a limited set of events to do some functionalities such as Filtering, Zooming, etc. The list of events defined in the DC.js are as follows −

  • renderlet − Fired after transitions are redrawn and rendered.

  • pretransition − Fired before the transitions start.

  • preRender − Fired before the chart rendering.

  • postRender − Fired after the chart finishes rendering including all the renderlet's logic.

  • preRedraw − Fired before chart redrawing.

  • postRedraw − Fired after the chart finishes redrawing including all the renderlet's logic.

  • filtered − Fired after a filter is applied, added or removed.

  • zoomed − Fired after a zoom is triggered.

basicMixin provides a method, on(event, listener) to set the callback function for all the above defined events.

  • on(event, listener) − Sets the callback or listener function for the specific event.

  • onClick(datum) − It 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.

Rendering Options

The basicMixin provides a list of methods to render the charts. They are used to draw the chart and they are as follows −

  • render() − Renders the chart. Generally, it will be used first, when the chart is drawn.

  • renderGroup() − Renders all the charts in the group as this chart belongs.

  • renderLabel( [renderLabel]) − Turns on/off label rendering.

  • renderTitle( [renderTitle]) − Turns on/off title rendering.

  • redraw() − Redraws the entire chart.

  • redrawGroup() − Redraws all charts in the group as this chart belongs.

Transition Options

The basicMixin provides methods to set the transition effect of the chart and they are as follows −

  • transitionDelay( [delay]) − Sets or gets the animation transition delay (in milliseconds) for this chart instance.

  • transitionDuration( [duration]) − Sets or gets the animation transition duration (in milliseconds) for this chart instance.

  • useViewBoxResizing( [useViewBoxResizing]) − If set, resizes the chart according to the SVG viewbox attributes.

  • controlsUseVisibility( [controlsUseVisibility]) − if set, uses the visibility attribute instead of the display attribute to show / hide a chart reset and filter controls.

In the next chapter, we will understand capMixin.

Advertisements