api

API Reference

Chart

• d3.chart
• <selection>.chart
• <instance>.trigger
• <instance>.on
• <instance>.once
• <instance>.off

---

#### `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