api

API Reference

Chart

Creation:

• d3.chart

Instantiation:

• <selection>.chart

Instance methods:

• <instance>.trigger
• <instance>.on
• <instance>.once
• <instance>.off
• <instance>.layer

---

#### `d3.chart(name, options)`

Description:

Used to define a new chart type.

Parameters:

• name - the name of the chart one wishes to create. This is the generic 'type' of chart you're creating, for example 'barchart' rather than an instance of a chart that you're initializing.
• options - the methods that will be available to the chart instance. See creating for more information on defining a chart.

Uses:

Example chart creation:

d3.chart('MyChartType', {
  initialize: function() {
  }
  // any additional instance methods go here.
});

---

#### `.chart(name)`

Description:

Used to create a chart instance on a selection or retrieve the chart reference within a layer.

Parameters:

• name - the name of the chart one wishes to use. Optional.

Uses:

There are two types of uses for the .chart method when called on a selection:

1. To initialize a chart from a selection. For example:

var chart = d3.select("div#vis")
  .append("svg")
  .attr("width", 200)
  .attr("height", 200)
  .chart("BarChart"); // assuming we've defined a BarChart chart type.

2. To retrieve the chart associated with a layer from within the layer methods:

// from within a chart definition:
chart.layer({
  dataBind: function(data) {
    var chartInstance = this.chart();
  }
});

Note you can only retrieve the chart from the layer, not from any selection that could possibly live within a chart's DOM tree.

---

<instance>.trigger(name)

Description:

Used to trigger an event on a chart. At least the name of the event is required. Any arguments passed after the name parameter will be passed to the callback.

Parameters:

• name - Name of event to trigger.

Uses:

For example:

var chart = d3.select("#vis")
	.append("svg")
	.chart("MyChart");

chart.on("AnEvent", function() {
  // react to said event
});	
chart.on("SomeEvent", function(arg1, arg2) {
  //react to said event
});

chart.trigger("AnEvent");
chart.trigger("SomeEvent", 12, 14);

---

<instance>.on(name, callback, context)

Description:

Binds a callback to the chart instance for a specific event name. Optionally can provide a context in which the callback be executed. By default, the context will be that of the chart instance.

Parameters:

• name - Name of the event to bind to
• callback - The callback to execute when that event triggers
• context - The context in which the callback will be executed. Optional.

Uses:

Example:

var chart = d3.select("#vis")
	.append("svg")
	.chart("MyChart");
	
chart.on("SomeEvent", function(arg1, arg2) {
  //react to said event
});

chart.trigger("SomeEvent", 12, 14);

---

<instance>.once(name, callback, context)

Description:

Binds a callback to the chart instance for a specific event name. This callback will only execute once. Optionally can provide a context in which the callback be executed. By default, the context will be that of the chart instance.

Parameters:

• name - Name of the event to bind to
• callback - The callback to execute when that event triggers
• context - The context in which the callback will be executed. Optional.

Uses:

Example:

var chart = d3.select("#vis")
	.append("svg")
	.chart("MyChart");
	
chart.once("SomeEvent", function(arg1, arg2) {
  //react to said event
  console.log(arg1, arg2);
});

chart.trigger("SomeEvent", 12, 14); // => 12,14
chart.trigger("SomeEvent", 20, 34); // nothing happens.

---

<instance>.off(name, callback, context)

Description:

Used to unbind events previously bound to the chart.

Parameters:

• name - Name of event to unbind. Optional.
• callback - The specific callback to unbind. Optional.
• context - The context for which to unbind.

Uses:

• Calling .off without any parameters will result in all events being unbound:

var chart = d3.select("#vis")
	.append("svg")
	.chart("MyChart");

chart.on("AnEvent", function() {
  // react to said event
});	
chart.on("SomeEvent", function(arg1, arg2) {
  //react to said event
});

chart.off(); //unbinds both AnEvent and SomeEvent

• Calling .off with a name parameter will result in all events bound to that event name being unbound:

var chart = d3.select("#vis")
	.append("svg")
	.chart("MyChart");

chart.on("AnEvent", function() {
  // react to said event
});	
chart.on("SomeEvent", function(arg1, arg2) {
  //react to said event
});

chart.off("AnEvent"); //unbinds AnEvent, but not SomeEvent

• Calling .off with a callback will unbind all events for which that callback is set. A name can be provided but isn't required.

var chart = d3.select("#vis")
	.append("svg")
	.chart("MyChart");

var callback = function() {
  // react to event
};
chart.on("AnEvent", callback);	
chart.on("SomeEvent", callback);

chart.off("SomeEvent", callback); // unbines only the SomeEvent callback
chart.off(undefined, callback);   //unbinds both AnEvent and SomeEvent

• Calling .off with a context will unbind all events for which that the callback will execute with said context. The name and callback can be provided by are not required.

var chart = d3.select("#vis")
	.append("svg")
	.chart("MyChart");

var context = {};
var callback = function() {
  // react to event
};
chart.on("AnEvent", callback, context);	
chart.on("SomeEvent", callback, context);

chart.off(undefined, undefined, context); //unbinds both AnEvent and SomeEvent
chart.off("AnEvent", undefined, context);   //unbinds AnEvent
chart.off(undefined, callback, context);   //unbinds both AnEvent and SomeEvent

<instance>.layer(name, selection, options)

Description:

Defines a new layer on a chart or returns a reference to the selection corresponding to a layer by a specific name.

Parameters:

• name - Name of event to unbind. Optional.
• selection - The d3 selection that will be made into a layer.
• options - The specific options available during layer creation:
  • events - An object specifying lifecycle events. Keys are the event names and the values are the callbacks.
  • dataBind - The function that sets up the selection and binds the data using the d3 .data() function. Must return that binding. Takes one argument which is the data that draw was called with, transformed if the transform method was defined. The context of the dataBind method is the selection of the layer.
  • insert - The function that gets called once the d3 .enter() method is executed. Note that happens internally. The context of the insert function is the entered selection.

Uses:

1. To create a new layer:

d3.chart("MyChart", {
  initialize: function() {

    // define a selection that will be used
    // to display our rects
    var barArea = this.base.append("g")
      .classed("bars", true);

    // create a new layer on the chart    
    this.layer("bars", barArea, {
      events: {

        // when new data enters, set its x attribute
        // according to the value of the datum.
        "enter" : function() {
          return this.attr("x", function(d) { 
            return d.value; 
          });
        }
      },
      dataBind: function(data) {
        // return a selection & data binding
        return this.selectAll("rect")
          .data(data);
      },
      insert: function() {
        // once the selection has been entered, append
        // the appropriate elements. Note we are not actually
        // setting the data-driven attributes here - those happen
        // on the enter event.
        return this.append("rect");
      }
    });
  }
});

2. To return a layer:

var chart = d3.select("#vis")
  .append("svg")
  .chart("MyChart");
  
var barLayer = chart.layer("bars");

This is most useful when extending the chart to include custom or additional functionality.