Extension:Plotters

MediaWiki extensions manual

Plotters Release status: beta
Implementation	Parser function
Description	Allows users to create client side graphs (like pie, bar, etc), and do generic canvas drawing from data using admin created javascript.
Author(s)	Ryan Lane
Latest version	0.6b (2009-06-04)
MediaWiki	1.14+ (possibly others - untested)
License	GPL, MIT (for fixencoding.js), Apache (for excanvas.js)
Download	SVN [?]: svn checkout URL browse file tree commit history Template:WikimediaDownload/svn
Example	http://ryandlane.com/sandbox/Plotters
Hooks used OutputPageParserOutput LanguageGetMagic ArticleSaveComplete
Translate the Plotters extension if it is available at translatewiki.net
Check usage and version matrix; code metrics

Usage

Special:Plotters

The list of available plotters is defined on MediaWiki:Plotters-definition. Plotters defined there can be used in <plot></plot> or {{#plot:}} calls. An overview of the plotters defined by MediaWiki:Plotters-definition is also shown on Special:Plotters, along with links to the respective system messages, for easy editing.

Each line in MediaWiki:Plotters-definition that starts with one or more "*" (asterisk) characters defines a plotter; it must have the following form:

* myplotter|myplotter.js

That is, each line consists of fields separated by a "|" (pipe) character. The first field ("myplotter" in the example) is the plotters internal name, and references a system message (MediaWiki:Plotter-myplotter in the example) that contains a short description of the plotter, using wiki syntax.

 Note: The internal name must start with a ASCII letter, and must contain only ASCII letter and numbers!

The remaining fields on the line refer to the JavaScript code that makes up the plotter, contained in system messages (MediaWiki:Plotter-myplotter.js in the example); the names of those messages must end with ".js". A plotter can use any number of code messages, specifically, common code can be put into a code message used by several plotters, in addition to their own specific code, e.g:

* bar|commonStuff.js|bar.js
* pie|commonStuff.js|tools.js|pie.js

The list of plotters in MediaWiki:Plotters-definition can be broken into sections using lines that start and end with two or more "=" (equals) characters, enclosing the name of a system message that defines the section's name - for example:

 == plotkit-scripts ==

This would define a new section, with the title defined on the page MediaWiki:Plotter-section-plotkit-scripts

Arguments

name 

A name for the plot. This is required for multiple plots in the same article. Only alpha-numeric characters are allowed, and only up to 255 characters; the default is plot

renderer 

The type of renderer to use; only plotkit and generic are available currently; the default is generic

width 

A greater than zero number in pixels to modify the width of the canvas; the default is 300

height 

A greater than zero number in pixels to modify the height of the canvas; the default is 300

script 

The plotter script to use. This is the script used to draw on the canvas. Only alpha-numeric characters are allowed, and only up to 255 characters; no default

scriptarguments 

A comma delimited list of arguments to be sent to the script. Commas that need to be sent as an argument can be escaped with a \. ; no default

preprocessors 

A comma delimited list of preprocessors. These will be called in order, and can be used to modify data and labels before the plotter script is called. Only alpha-numeric characters are allowed, and only up to 255 characters per preprocessor; no default

preprocessorarguments 

a comma and colon delimited list of arguments to pass to the preprocessors; no default

datasep 

The delimiter for the data; the default is ,

labels 

A comma delimited list of labels for the data. Only alpha-numeric characters are allowed, and only up to 255 characters per label; no default

tableclass 

The CSS class used for the javascript fallback table. Only alpha-numeric characters are allowed, and only up to 255 characters; the default is wikitable

Scripts and preprocessors

Preprocessing scripts, and plotting scripts are available, and the javascript function for each should be defined as follows:

/* For preprocessing scripts */
function plotter_<preprocessorname>_process( name, data, labels, arguments ) {
    /* example preprocessor: */
    for ( var i = 0; i < data.length; ++i ) {
        for ( var j = 1; j < data[i].length; ++j ) {
            data[i][j] = data[i][j] * 2;
        }
    }
}

/* For plotting scripts */
function plotter_<scriptname>_draw( name, data, labels, arguments ) {
    /* example plotkit script: */
    var plotkitlabels = [];
    for ( var i = 0; i < labels.length; ++i ) {
        plotkitlabels[i] = { v:i, label:labels[i] };
    }
    var options = { "xTicks": plotkitlabels };
    var layout = new PlotKit.Layout("bar", options);
    layout.addDataset("data", data);
    layout.evaluate();
    var canvas = MochiKit.DOM.getElement(name);
    var plotter = new PlotKit.SweetCanvasRenderer(canvas, layout, options);
    plotter.render();
}

You can use these in a parser function like so:

{{#plot:
|renderer=plotkit
|script=<scriptname>
|scriptarguments=arg1,arg2,...
|preprocessors=<preprocessorname1>,<preprocessorname2>,...
|preprocessorarguments=<preprocessor1argument1>,<preprocessor1argument2>,...:preprocessor2argument1>,<preprocessor2argument2>,...:...,...
|labels=label1,label2
|data=1,2
2,4}}

 Note: Script arguments, preprocessor arguments, labels, and data are all initially sent as strings to functions for security reasons. If a script requires non-strings, your functions should cast as required.

Requirements

• PlotKit, if the plotkit renderer is to be used
  • MochiKit is a requirement for PlotKit

Installation

1. Download the extension from the above link
2. Download prerequisite javascript (such as PlotKit and MochiKit) and place them in a web-server retrievable directory of your choosing
3. Add the following line to the end of LocalSettings.php:

   require_once( "$IP/extensions/Plotters/Plotters.php" );

4. Add configuration lines to the end of LocalSettings.php:

   $wgPlottersJavascriptPath = "/scripts";

   $wgPlottersRendererFiles = array( "customrenderer" => array( "/customjs/Custom.js", "/customjs/MoreCustom.js", "..." ) );

   • By default the plotkit renderer's javascript files are defined; you may override them if you wish
   • The javascript defined in $wgPlottersRendererFiles will be searched for under $wgPlottersJavascriptPath; for example, if your url is http://example.com:

     http://example.com/scripts/customjs/Custom.js

     http://example.com/scripts/customjs/MoreCustom.js

     http://example.com/scripts/customjs/...

Pre-made scripts

Plotkit

• Extension:Plotters/Plotkit scripts

Javacript libraries for plotting

• Flot
• Protochart
• Table to chart - needs additional extension support that will be added soon
• Plotkit
• RGraph (still alpha - proprietary license)
• jqPlot