Extension:Plotters

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.png
Plotters

Release status:Extension status unmaintained

ImplementationTemplate:Extension#type Parser function
DescriptionTemplate:Extension#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)Template:Extension#username Ryan Lane
Latest versionTemplate:Extension#version 0.6b (2009-06-04)
MediaWikiTemplate:Extension#mediawiki 1.14+ (possibly others - untested)
LicenseTemplate:Extension#license GPL, MIT (for fixencoding.js), Apache (for excanvas.js)
Download Template:WikimediaDownload/svn
ExampleTemplate:Extension#example http://ryandlane.com/sandbox/Plotters
Hooks usedTemplate:Extension#hook
OutputPageParserOutputManual:Hooks/OutputPageParserOutput
LanguageGetMagicManual:Hooks/LanguageGetMagic
ArticleSaveCompleteManual:Hooks/ArticleSaveComplete

Translate the Plotters extension if it is available at translatewiki.net

Check usage and version matrix.

Usage[edit]

Special:Plotters[edit]

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 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[edit]

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[edit]

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 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[edit]

  • PlotKit, if the plotkit renderer is to be used

Installation[edit]

  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[edit]

Plotkit[edit]

Javacript libraries for plotting[edit]