PlotKit Home | << | >>

PlotKit Renderer

A Renderer is responsible for translating the layout calculated by PlotKit.Layout and draw it on to a HTML Canvas, SVG object or any other way. One way to use the renderer is to allow theming of graphs by tweaking the layout.

PlotKit includes some common basic renderers, so you do not need to customise anything if you just plan to change the spacing, colors, fonts, or layout.

PlotKit Renderers should follow an informal protocol to allow users to plug and play different renderers. Below is the informal protocol:

PlotKit Renderer Protocol

element is the element which this renderer will perform on, layout is the PlotKit.Layout object and options is an associative dictionary described below.

Optional check that returns true if the renderer is supported in the current browser.

Renders to canvas, can be called multiple times, but clear() must be called between invokations.

Clear the canvas.

PlotKit Renderer Options

To allow some basic flexibility of the output, a renderer should accept and act on the following options passed in the constructor.

Option nameDescriptionTypeDefault
backgroundColor color to use for background MochiKit.Color.Color Color.whiteColor()
colorScheme Color scheme used Array of MochiKit.Color.Color output of PlotKit.Base.colorScheme()
strokeColor Color used stroking. If set to null, the renderer will attempt to use strokeColorTransform MochiKit.Color.Color or null null
strokeColorTransform Name of the method to call to transform Color into stroke color. string (name of a function that accepts no arguments) "asStrokeColor"
drawBackground Whether the background should be drawn boolean true
shouldFill Should fill in area under chart boolean true
shouldStroke Should stroke the borders of shapes in chart boolean true
strokeWidth Width of stroke used (if shouldStroke is set) float 0.1
padding Padding of the graph drawn (excluding labels) Object with properties: top, bottom, left, right. {left: 30, right:20, top: 10, bottom: 10}
drawYAxis draw Y Axis boolean true
drawXAxis draw X Axis boolean true
axisLineColor Color of axes line. MochiKit.Color.Color Color.blackColor()
axisLineWidth axis line width float 0.5
axisTickSize length or height of a tick on the y and x axis respectively, in pixels float 3.0
axisLabelColor color of text label on axis. MochiKit.Color.Color Color.blackColor()
axisLabelFontSize Font size of labels in pixels integer 9
axisLabelWidth Width of labels on ticks, in pixels integer 50
enableEvents Enable events (if supported) boolean true

Internal Renderer Methods and Style

The default renderers that are available follow a rough structure. If you plan to write a new renderer, you should think about using a similar structure.

Also, it is important that you follow an Object Orientated style and split up the rendering methods as much as logically possible to allow other developers to extend the work by using a "psuedo subclassing" method described below.

Subclassing

PlotKit Renderers should adopt a Javascript subclassing structure to allow developers/themers to customise certain aspects of the rendering. Here is an example of what is expected: 

MyRenderer = function(element, layout, options) {
    if (arguments.length  > 0)
       this.__init__(element, layout, options);
};

MyRenderer.prototype.__init__ = function(element, layout, options) {
  ....
};

In this case, the default javascript constructor acts only when passed arguments. MyRenderer.prototype.__init__ is the real constructor. It is named in similar vein to Python's constructor.

For users who would like to subclass, they will need to use the following snippet of code: 

 MyAlternateRenderer = function(element, layout. options) {
   if (arguments.length > 0) 
      this.__init__(element, layout, options);
 };
 MyAlternateRenderer.prototype = new MyRenderer();
 MyAlternateRenderer.prototype.constructor = MyAlternateRenderer;
 MyAlternateRenderer.__super__ = MyRenderer.prototype;

 MyAlternateRenderer.prototype.__init__ = function(element, layout, options) {
     MyAlternateRenderer.__super__.__init__.call(this, element, layout, options);
 };

For subclasses, they will need the following magic in order to initialise their subclass. But after that, you can either override MyAlternateRenderer.prototype.__init__ with your own implementation or just leave the superclass to deal with the constructor.

A more thorough example can be found in the PlotKit source for Canvas.js and SweetCanvas.js respectively.

Internal Renderer Properties

The bundled renderers are have the following common properties to allow standard access by all subclasses:

The PlotKit.Layout object passed by the user.

The HTML element to use, either a Canvas Element or SVG Element depending on whether a Canvas Renderer or SVG Renderer is in use.

A dictionary of options that are applicable to the rendering style.

A list of elements that represent the axis. Should be cleared whenever clear() is executed.

A list of elements that represent the axis. Should be cleared whenever clear() is executed.

Internal Renderer Methods

Renders only the bars of a bar chart on the element by looking at this.layout.bars for the bars to render. Will only be called if this.layout.style == "bars"

Renders only the lines of a line chart on the element by looking at this.layout.points for the points to render. Will only be called if this.layout.style == "line"

Renders only the slices of the pie in this.layout.slices. Will only be called if this.layout.style == "pie"

Renders the axis for a bar chart by looking at the this.layout.xticks and this.layout.yticks.

Renders the axis for a line chart by looking at the this.layout.xticks and this.layout.yticks.

Renders the labels for a pie chart by looking at this.layout.xticks only.

Called to render the background of the chart. Should check whether this.options.drawsBackground is set before proceeding.

Events from the Chart

There is preliminary support for events from the chart for the Canvas Renderer but the API is not stablised and subject to change. (TODO).