Template:Highcharts

Documentation

This box includes basic usage information for this template. When calling the template, this documentation will not appear. Functional template code should be placed outside the dotted box.

Unsafecontent Permission Check

// This code checks if the template is properly installed for unsafe content execution,
// and may be removed if this check is not desired.  If you leave this here, add your new code
// in a new DekiScript block below this one.
var thisTemplate = wiki.inclusions()[-1];
if (!wiki.pagepermissions(thisTemplate.id, thisTemplate.author.id).unsafecontent)
  <div style="color:red; width:75%; padding:5px; border:1px solid red;">
    "WARNING: The page '"..thisTemplate.path.."' must be re-saved by a user with UNSAFECONTENT permission in order to work correctly. ";
    <a href="http://developer.mindtouch.com/en/kb/Using_templates_which_require_UNSAFECONTENT_permission"> "See this" </a>;
    " for more info."; 
  </div>;

Parameter Processing

// Errors array.  There's lots of error checking to do, even if we can't possibly cover everything
var errors = [];
var fatal = false;

// Convenience variables for all the different series types
var line = "line";
var spline = "spline";
var area = "area";
var areaspline = "areaspline";
var column = "column";
var bar = "bar";
var pie = "pie";
var scatter = "scatter";
var raw = "raw";

// ====================
//  Process Parameters
// ====================

// == Core Parameters ==

// type: what kind of chart (OPTIONAL; default "line")
var validTypes = [ line,spline,area,areaspline,column,bar,pie,scatter,raw ];
var type = $0 ?? $type ?? line;
if (type is str) let type = string.tolower(type); 
if (!list.contains(validTypes, type)) {
    let errors ..= [ ("TYPE parameter must be one of "; validTypes) ];
}

// size: dimensions of chart area, in pixels (OPTIONAL; default 400x200)
var size = $1 ?? $size ?? [ 400, 200 ];
if (size is not list || size[0] is not num || size[1] is not num) {
    let errors ..= [ "SIZE parameter must be a list of two numbers" ];
}

// data: chart data.  This is always a list, with each list element a data series (REQUIRED)
var data = $2 ?? $data;
if (data is not list) {
    let errors ..= [ "FATAL: DATA parameter must be a list of data series" ];
    let fatal = true;
}

// options: all other options for the chart (OPTIONAL)
var options = $3 ?? $options ?? {};
if (options is not map) {
    let errors  ..= [ "OPTIONS parameter must be a map" ];
}

// data label formatter
var labelFormatter = $4 ?? $labelFormatter;
if (labelFormatter is not nil && labelFormatter is not str) {
    let errors ..= [ "LABELFORMATTER parameter must be a string" ];
    let labelFormatter = nil;
}
        
// tooltip formatter
var tooltipFormatter = $5 ?? $tooltipFormatter;
if (tooltipFormatter is not nil && tooltipFormatter is not str) {
    let errors ..= [ "TOOLTIPFORMATTER parameter must be a string" ];
    let tooltipFormatter = nil;
}

// debug
var debug = $6 ?? $debug ?? false;

// == Convenience Parameters ==

// animation
var animation = $animation ?? false;
if (animation is not bool) {
    let errors ..= [ "ANIMATION parameter must be bool" ];
    let animation = false;
}

// categories
var categories = $categories;
if (categories is not nil && categories is not list) {
    let errors ..= [ "CATEGORIES must be a list of category names" ];
    let categories = nil;
}

// stacking
var stacking = $stacking;
if (stacking is not nil && !list.contains(["normal", "percent"], stacking)) {
    let errors ..= [ "STACKING parameter must be either 'normal' or 'percent'" ];
    let stacking = nil;
}

// title
var title = $title;
if (title is not nil && title is not str) {
    let errors ..= [ "TITLE parameter must be a string" ];
    let title = nil;
}

// Construct the chart options
var chartOptions;
if (type == raw) {
    let chartOptions = { chart: { renderTo: @holder }, series: data };
}
else {
    // Chart: should be derived from user-specified options
    var titleMargin  = (#title ? 40 : 0);
    var topMargin    = titleMargin + (type == pie ? 0 : (titleMargin ? 40 : 50));
    var bottomMargin = (type == pie ? 0 : 30);
    var leftMargin   = (type == pie ? 30 : 60);
    var rightMargin  = (type == pie ? 0 : 10);
    var specChart = {
        renderTo: @holder,
        defaultSeriesType: type,
        margin: [ topMargin, rightMargin, bottomMargin, leftMargin ],
        borderRadius: 5
    };

    // Tooltip
    var specTooltip = {};

    // plotOptions: Very specific to chart type
    var specPlotOptions = { series: { animation: animation, stacking: stacking } };
    if (type == pie) let specPlotOptions ..= {
        pie: {
            allowPointSelect: true,
            dataLabels: {
                enabled: true,
                color: "white"
            },
            center: [ num.min(size[0],size[1]) / 2 + 10, "50%" ]
        }
    };

    // Credits: turn off "Highcharts" credit
    var specCredits = { enabled: false };

    // Title
    var specTitle = {
        text:title,
        x: 25,
        y: 30,
        style: {
            color: "black",
            fontWeight: "bold",
            fontSize: "18px"
        }
    };

    // Legend
    var specLegend =
        type == pie ?
        {
            layout: "vertical",
            borderRadius: 5,
            align: "right",
            verticalAlign: "middle",
            x: -30,
            y: 0
        } :
        {
            layout: "horizontal",
            borderRadius: 5,
            verticalAlign: "top",
            x: 25,
            y: (#title ? 45 : 10)
        };

    // X axis
    var specXaxis = {
        categories : categories
    };

    // Y axis
    var specYaxis = {
    };

    // Series
    var specSeries =
        type == pie ?
        [ { data: data } ] :
        data;
    
    // Assemble it all
    let chartOptions = {
        chart: specChart,
        tooltip: specTooltip,
        plotOptions: specPlotOptions,
        credits: specCredits,
        title: specTitle,
        legend: specLegend,
        xAxis: specXaxis,
        yAxis: specYaxis,
        series: specSeries
    };
}

// Merge user-supplied options into chartOptions
foreach (var k:v in options) {
    if (v is not map) let errors ..= [ "OPTIONS arg: '"..k.."' element must be a map" ];
    let chartOptions ..= {
        (k) : (chartOptions[k]??{}) .. { (kk):(vv is map ? chartOptions[k][kk]..vv : vv) foreach var kk:vv in v }
    };
}

Output Generation

if (#errors) <div style="color:red">
    <strong> "Highcharts errors:" </strong>;
    <ul> foreach (var e in errors) <li> e </li>; </ul>;
</div>;
else <html>
<head>

<script type="text/javascript" src=(thisTemplate.files["highcharts.js"].uri)></script>;
<script type="text/javascript">
" $(function() {
    var options = "..json.emit(chartOptions)..";
";
// Add formatter(s) if necessary
if (labelFormatter is not nil) "
    if (options.plotOptions.series.dataLabels == null) options.plotOptions.series.dataLabels = {};
    options.plotOptions.series.dataLabels.formatter = function(){ "..labelFormatter .. " };
";

if (tooltipFormatter is not nil) "
    if (options.tooltip == null) options.tooltip = {};
    options.tooltip.formatter = function(){ "..tooltipFormatter.." };
";

// Resume
"   var chart = new Highcharts.Chart(options);
});
" </script>;

</head>;
<body>

if (debug) <div style="color:red; border: 1px dotted red; padding:10px;">
    <strong> "Highcharts debug output" </strong>;
  <div>
    "Here are the parameters passed to the ";
    web.link("http://developer.mindtouch.com/User:neilw/Templates_and_Extensions/Highcharts_-_a_wrapper_for_the_Highcharts_JavaScript_graphing_package",
             "template"); ":";
    <div style="margin-left: 20px"> prettyPrint(args) </div>;
    "Here is the generated argument map passed to "; web.link("http://www.highcharts.com/ref/", "Highcharts"); ":";
    <div style="margin-left: 20px"> prettyPrint(chartOptions) </div>;
    if (labelFormatter is not nil)
        <div> "The custom datalabel formatter is: "; <strong> "function() { " .. labelFormatter .. " }" </strong>; </div>;
    if (tooltipFormatter is not nil)
        <div> "The custom tooltip formatter is: "; <strong> "function() { " .. tooltipFormatter .. " }" </strong>; </div>;
    <div> "The resulting chart appears below this box." </div>;
  </div>;
</div>;

<div id=(@holder) style=("width:"..size[0].."px; height:"..size[1].."px;")/>;

</body>;
</html>;