layers adding

Layers: Adding

When creating a layer, there are three required components:

1. The name of a layer. This will be used to retrieve it later and should generally describe the type of markers being drawn
2. The selection into which the layer elements will be drawn.
3. The set of instructions on how the layer will be constructed.

Where are layers created?

By default, the layer creation happens inside the initialize method of your chart. For example:

d3.chart("CircleChart", {
  initialize: function() {
    // add a layer
    //  - name it "circles"
    //  - create a new group element to house all the elements it will create.
    this.layer("circles", this.base.append("g"), {
        //...
    });
});

How does one create a new selection for the layer?

The layer elements should all go into some parent element. It is likely you want that parent element to be a child of the base container of the chart. You always have access to this.base in the context of a chart, which will reference that root element. Simply create a new selection on it with d3 into which you can add elements, for eample:

this.base.append("g");

What are the required instructions for creating a layer?

A layer needs to know:

• What to bind data to
• What elements to insert
• How to handle changes in the data.

This results in the following required properties on the third argument to the .layer function:

1. dataBind: function(data) {}
2. insert : function()
3. events : {}

dataBind

The function that sets up the selection and binds data to it using the d3 .data() function. Must return that binding. For example:

dataBind: function(data) {
  return this.selectAll("circle")
    .data(data);
}

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. For example:

insert: function() {
  // return a new selection insertion. 
  return this.insert("circle")
    .attr("cy", 100)
    .attr("r", 4)
    .style("fill", "red");
},

events

An object specifying lifecycle events. Keys are the event names and the values are the callbacks. For example:

events: {
  // when new data come in, put it through the
  // enter callback, positioning the circles according to
  // the data points
  "enter": function() {
    this.attr("cx", function(d) { 
      return d; 
    });
  },

  // when data points are removed, remove the corresponding
  // selected elements.
  "exit": function() {
    this.remove();
  }
}

All together:

The following chart positions circles along the x axis, using the values for their position.

d3.chart("CircleChart", {
  initialize: function() {
    
    // create a circle layer
    this.layer("circles", this.base.append("g"), {

      // make the selection that data should be bound to and bind 
      // the date to it.
      dataBind: function(data) {
        return this.selectAll("circle")
          .data(data);
      },
      insert: function() {
        // return a new selection insertion. 
        return this.insert("circle")
          .attr("cy", 100)
          .attr("r", 4)
          .style("fill", "red");
      },
      events: {
        // when new data come in, put it through the
        // enter callback, positioning the circles according to
        // the data points
        "enter": function() {
          this.attr("cx", function(d) { 
            return d; 
          });
        },

        // when data points are removed, remove the corresponding
        // selected elements.
        "exit": function() {
          this.remove();
        }
      }
    });
  }
});