API Documentation

girlwithglasses edited this page Jan 26, 2016 · 9 revisions
Clone this wiki locally

API Reference

Chart

Creation:

Extension

Instance methods:

Layer

Creation

Instance Methods:

Chart

Creating a koto chart

Description:

All charts extend the koto.Base class (or another koto chart). We attach all chart constructors to the global koto variable.

Uses:

Sample chart creation:

class MyChartName extends koto.Base {
  constructor(selection){
    super(selection);
    // initialize chart here
  }
  // optionally over-ride methods
  transform(data){
    return data.reverse();
  }
}

// we attach everything to the global `koto` variable
koto.MyChartName = MyChartName;

Koto[chartName].extend(Object || function)

Description:

Create a new koto 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. This is usefull if you would like to extend a chart and you don't have ES6 available to you.

Parameters:

  • Object - An object with an initialize method and any other method over-rides.
  • Function - An initialize (constructor) function for chart.

Returns: A koto chart constructor function.

Uses:

Example:

// define a new chart type:
koto.BarChart = classFn;

// extend it with initialize function:
koto.ExtendedBarChart = koto.BarChart.extend(function () {
  var chart = this; // this is a BarChart instance;
});

// create an extended chart type instance:
var chart = new koto.ExtendedBarChart(d3.select('#vis'));

<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 = new koto.MyChart(d3.select('#vis'));

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 = new koto.MyChart(d3.select('#vis'));

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 = new koto.MyChart(d3.select('#vis'));

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 = new koto.MyChart(d3.select('#vis'));

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 = new koto.MyChart(d3.select('#vis'));

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 = new koto.MyChart(d3.select('#vis'));

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 = new koto.MyChart(d3.select('#vis'));

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

Layer

<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. You can also define these events using the familiar 'on' syntax.

Uses:

  1. To create a new layer:
koto.MyChart = class extends koto.Base {
  constructor() {

    // 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');
      }
    })
    .on('enter', function () {
      //`this` is the 'enter' selection
    });
  }
};
  1. To return a layer:
var chart = new koto.MyChart(d3.select('#vis'));

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 = new koto.MyChart(d3.select('#vis'));

// 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 = new koto.MyChart(d3.select('#vis'));

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:

koto.MyChart = class extends koto.Base {
  constructor(selection) {
    super(selection);
  }
  transform(data) {
    return data.values;
  }
};

var chart = new koto.MyChart(d3.select('#vis'));

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 - <koto.Chart instance> koto.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
koto.BarChart = classFn;
koto.PieChart = anotherClassFn;

koto.SuperChart = class extends koto.Base {
  constructor(selection) {
    super(selection);

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

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

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

// Create a super chart instance.
var chart = new koto.SuperChart(d3.select('#vis'));

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

<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
koto.MyChart = class extends koto.Base {
  constructor() {

    // 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');
      }
    })
    .on('enter', function () {
      //`this` is the 'enter' selection
    });
  }
};

var chart = new koto.MyChart(d3.select('#vis'));

// get the layer
var layer = chart.layer('bars');

// 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:

// define a layer
koto.MyChart = class extends koto.Base {
  constructor() {

    // 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
    var barLayer = 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');
      }
    });

    barLayer.on('enter', function () {
      //`this` is the 'enter' selection
    });
  }
};

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

// define a layer
koto.MyChart = class extends koto.Base {
  constructor() {

    // 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
    var barLayer = 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');
      }
    });

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

    setTimeout(function() {
      barLayer.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.