apiv2

API Reference

For API reference for d3.chart v0.1.x, see the previous API spec here

Chart

Creation:

• d3.chart

Extension

• d3.chart(chartType).extend

Instantiation:

• <selection>.chart

Instance methods:

• <instance>.trigger
• <instance>.on
• <instance>.once
• <instance>.off
• <instance>.layer
• <instance>.unlayer
• <instance>.draw
• <instance>.transform
• <instance>.attach

Layer

Creation

• <selection>.layer

Instance Methods:

• <instance>.draw
• <instance>.on
• <instance>.off
• <instance>.dataBind
• <instance>.insert

---

Chart

d3.chart(name, options, staticProps)

Description:

Create a new chart constructor or return a previously-created chart constructor.

Parameters:

• name - name If no other arguments are specified, return the previously-created chart with this name.
• options - If specified, this value will be forwarded to Chart.extend and used when creating new chart instances.
• staticProps - If specified, this value will be forwarded to Chart.extend and used to define properties on the chart constructor function.

Returns: A chart constructor.

Uses:

Sample chart creation:

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

---

d3.chart(chartType).extend(name, protoProps, staticProps)

Description:

Create a new Chart constructor with the provided options acting as "overrides" for the default chart instance methods. Allows for basic inheritance so that new chart constructors may be defined in terms of existing chart constructors. Based on the extend function defined by Backbone.js.

Parameters:

• name - Identifier for the new Chart constructor.
• protoProps - Properties to set on the new chart's prototype. d3.chart reserves the following properties:
  • demux - A method specifying how data should be modified for individually attached charts. Takes two arguments: attachmentName and the full data passed to Chart#draw (after it was transformed.)
• staticProps - Properties to set on the chart constructor itself.

Returns: A chart instance.

Uses:

Example:

// define a new chart type:
d3.chart("MyChart", {});

// extend it:
d3.chart("MyChart").extend("MyExtendedChart", {
 hoverable: function() {}
});

// create an extended chart type instance:
var chart = d3.select("#vis")
  .append("svg")
  .chart("MyExtendedChart")
  .hoverable(); // method is now available.

---

<selection>.chart(chartName)

Description:

Instantiate a chart or return the chart that the current selection belongs to.

Parameters:

• name - The name of the chart to instantiate. If the name is unspecified, this method will return the chart that the current selection belongs to.
• options - The options to use when instantiating the new chart.

Returns: A reference to this chart (chainable.)

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({
  insert: 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:

Publish an event on this chart with the given name.

Parameters:

• name - Name of the event to publish.
• arguments - {...*} Values with which to invoke the registered callbacks.

Returns: A reference to this chart (chainable.)

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:

Subscribe a callback function to an event triggered on the chart. See once to subscribe a callback function to an event for one occurence.

Parameters:

• name - Name of the event
• callback - Function to be invoked when the event occurs
• context - value to set as this when invoking the callback. Defaults to the chart instance. Optional.

Returns:

A reference to this chart instance (chainable.)

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); // => 12,14
chart.trigger("SomeEvent", 20, 34); // => 20,34

---

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

Description:

Subscribe a callback function to an event triggered on the chart. This function will be invoked at the next occurance of the event and immediately unsubscribed. See Chart.on to subscribe a callback function to an event indefinitely.

Parameters:

• name - Name of the event
• callback - Function to be invoked when the event occurs
• context - alue to set as this when invoking the callback. Defaults to the chart instance. 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:

Unsubscribe one or more callback functions from an event triggered on the chart. When no arguments are specified, all handlers will be unsubscribed. When only a name is specified, all handlers subscribed to that event will be unsubscribed. When a name and callback are specified, only that function will be unsubscribed from that event. When a name and context are specified (but callback is omitted), all events bound to the given event with the given context will be unsubscribed.

Parameters:

• name - Name of the event to be unsubscribed
• callback - Function to be unsubscribed
• context - Contexts to be unsubscribed

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 event handlers that have been registered with that context. The name and callback can be provided but 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:

Interact with the chart's layers.

If only a name is provided, simply return the layer registered to that name (if any).

If a name and selection are provided, treat the selection as a previously-created layer and attach it to the chart with the specified name.

If all three arguments are specified, initialize a new Layer using the specified selection as a base passing along the specified options.

The Layer#draw method of attached layers will be invoked whenever this chart's Chart#draw is invoked and will receive the data (optionally modified by the chart's Chart#transform method.

Parameters:

• name - Name of the layer to attach or retrieve.
• selection - <d3.selection> The layer's base or a previously-created Layer.
• options - Options to be forwarded to the Layer constructor:
  • dataBind - The function that sets up the selection and binds data to it using the d3 .data() function. Must return that binding. dataBind 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 base 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.
  • events - An object specifying lifecycle events. Keys are the event names and the values are the callbacks.

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, {
      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");
      },
      events: {
        // when new data enters, set its x attribute
        // according to the value of the datum.
        enter: function() {
          this.attr("x", function(d) {
            return d.value;
          });
        }
      }
    });
  }
});

2. To return a layer:

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

var barLayer = chart.layer("bars");

---

<instance>.unlayer(name)

Description:

Remove a layer from the chart. Note that this does not hide the layer if it has been rendered.

Parameters:

• name - The name of the layer to remove.

Returns:

The layer removed by this operation. This layer can be reattached by invoking the Chart#layer method.

Uses:

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

// remove layer
var barLayer = chart.unlayer("bars");
barLayer.style("display", "none");

// reattach layer
chart.layer("bars", barLayer);

---

<instance>.draw(data)

Descripion:

Update the chart's representation in the DOM, drawing all of its layers and any "attachment" charts (as attached via Chart#attach).

Parameters:

• data - Data to pass to the draw of this chart's layers (if any) and the Chart#draw of this chart's attachments (if any).

Uses:

Example:

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

var data = [1,2,3,4];
chart.draw(data);

---

<instance>.transform(data)

Description:

By default, a passthrough that returns the exact data provided to the Chart#draw call.

Can be overwritten to reshape the data before it is passed to the chart layers and other attached charts.

Note you will most likely never call this method directly, but rather define it during chart constructor definition.

Parameters:

• data - The data to transform.

Returns:

Transformed data.

Uses:

d3.chart("MyChart", {
  transform: function(data) {
    return data.values;
  }
});

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

chart.draw({ values : [1,2,3] }); // results in [1,2,3] being passed to the
                                  // layers that will utilize the data.

---

<instance>.attach(attachmentName, chart)

Description:

Register or retrieve an "attachment" Chart. The "attachment" chart's draw method will be invoked whenever the containing chart's draw method is invoked.

Parameters:

• attachmentName - Name of the attachment. This does not correspond to a chart type but rather is a unique identifier that the chart creator wishes to give to their chart. This name can later be used during demux to return correct data for chart instance.
• chart - <d3.chart instance> d3.chart to register as a mix in of this chart. When unspecified, this method will return the attachment previously registered with the specified attachmentName (if any).

Uses:

For example if you have two chart types: BarChart and PieChart that you wish to combine into one super chart, you can create instances of them inside your super chart's initialize method and then attach them to the chart like so:

For example:

// Define your chart types
d3.chart("BarChart", {});
d3.chart("PieChart", {});

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

    // initialize a bar chart
    var bar = this.base.append("g").classed("bar", true)
      .chart("BarChart");

    // initialize a pie chart
    var pie = this.base.append("g").classed("pie", true)
      .chart("PieChart");

    // attach both charts to parent chart
    this.attach("bar", bar);
    this.attach("pie", pie);
  }
});

// Create a super chart instance.
var chart = d3.select("#vis")
  .append("svg")
  .chart("SuperChart");

chart.draw([1,2,3]); // will draw both, Bar and Pie charts.

---

Layer

Create a layer using the provided base. The layer instance is not exposed to d3.chart users. Instead, its instance methods are mixed in to the base selection it describes; users interact with the instance via these bound methods.

<selection>.layer(options)

Description:

Create a new layer on the d3 selection from which it is called.

Parameters:

• options - Options to be forwarded to Layer constructor. Must include dataBind and insert methods. May also include an events property. See Chart#layer for descriptions of those properties.

Uses:

Example:

// define a layer
var layer = d3.select("#vis")
  .append("svg")
  .layer({
    dataBind: function(data){
      return this.selectAll("rect")
        .data(data);
    },
    insert: function() {
      return this.append("rect");
    }
  });

// render the layer
layer.draw([1,2,3]);

---

<instance>.draw(data)

Description:

Render the layer according to the input data: Bind the data to the layer (according to Layer#dataBind, insert new elements (according to Layer#insert, make lifecycle selections, and invoke all relevant handlers (as attached via Layer#on or Layer#events) with the lifecycle selections:

• update
• update:transition
• enter
• enter:transition
• merge
• merge:transition
• exit
• exit:transition

Parameters:

• data - Data to drive the rendering.

Uses:

For example:

// define a layer
var layer = d3.select("#vis")
  .append("svg")
  .layer({
    dataBind: function(data){
      return this.selectAll("rect")
        .data(data);
    },
    insert: function() {
      return this.append("rect");
    },
    events: {
      enter: function() {
        this.attr("x", function(d) { return d.value; })
      }
    }
  });

// render the layer
layer.draw([1,2,3]);

---

<instance>.on(eventName, handler, options)

Description:

Subscribe a handler to a "lifecycle event". These events (and only these events) are triggered when Layer#draw is invoked--see that method for more details on lifecycle events.

Parameters:

• eventName - Identifier for the lifecycle event for which to subscribe. Allowed events (in order of occurance) are: update, enter, merge, exit, update:transition,enter:transition, merge:transition and exit:transition.
• handler - callback function
• options - Optional Arguments. Can include:
  • chart - The chart that should be the returned when a callback references this.chart(). This is particularly useful when building a single chart that is a combination of several through mixins.

Uses:

Example:

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

    // define a new test layer
    var layer = this.layer("layer1", this.base.append("g"), {
      dataBind: function(data) {
        return this.selectAll("rect")
          .data(data);
      },
      insert: function() {
        return this.append("rect");
      }
    });

    // bind to the layer's enter event the setting of the actual
    // position related attribute.
    layer.on("enter", function() {
      this.attr("x", function(d) {
        return d.x;
      });
    });
  }
});

---

<instance>.off(eventName, handler)

Description:

Unsubscribe the specified handler from the specified event. If no handler is supplied, remove all handlers from the event.

Parameters:

• eventName - Identifier for event from which to remove unsubscribe
• handler - Callback to remove from the specified event

Returns:

<d3.selection> Reference to the layer's base.

Uses:

For example:

function randomColor() {
  var color = Math.random() > 0.5 ? "red" : "papayawhip";
  this.style("fill", color);
}
var layer = d3.select("body").append("g").layer({
  dataBind: function(data) {
    return this.selectAll("rect")
      .data(data);
  },
  insert: function() {
    return this.append("rect");
  }
});

// Give a random color to any rectangle that is created within the next 2
// seconds.
layer.on("enter", randomColor);

setTimeout(function() {
  layer.off("enter", randomColor);
}, 2000);

---

<instance>.dataBind(data)

Description:

Invoked by Layer#draw to join data with this layer's DOM nodes. This implementation is "virtual"--it must be overridden by Layer instances.

Note you will never need to call this method directly. It is invoked as part of the draw call.

Parameters:

• data - data Value passed to Layer#draw

---

<instance>.insert()

Description:

Invoked by Layer#draw in order to insert new DOM nodes into this layer's base. This implementation is "virtual"--it must be overridden by Layer instances.

Note you will never need to call this method directly. It is invoked as part of the draw call.