Charts API
Moodle 3.2
Overview
The Charts API is a core set of methods intended to provide a simple and yet modern interface to generate dynamic charts.
Chart types
The first step to create a new chart is to create an instance of the desired chart type. At the moment bar, line and pie types are supported and using some display changing methods can change how the charts are displayed.
Bar
To create a new bar chart, just create a new instance of chart_bar class.
$chart = new core\chart_bar();
You might want change how your bar chart are displayed:
Stacked Bar
To display stacked bars, you can call set_stacked() method, setting the parameter to true.
$chart = new core\chart_bar();
$char->set_stacked(true); //Calling set_stacked() passing true as parameter will display stacked bars.
Horizontal Bar
To display you bar chart in the horizontal position, you need to call set_horizontal():
$chart = new core\chart_bar();
$char->set_horizontal(true); // Calling set_horizontal() passing true as parameter will display horizonal bar charts.
Line
To create a new line chart, just create an instance of chart_line class. By default, lines are tensioned.
$chart = new core\chart_line();
Smooth lines
You might want to change you line chart to display smooth lines:
$chart = new core\chart_line();
$chart->set_smooth(true); // Calling set_smooth() passing true as parameter, will display smooth lines.
Pie
To create a pie chart you just need to create a new instance of chart_pie class.
$chart = new core\chart_pie();
Doughnut
You might want to change you pie chart to be displayed as doughnut:
$chart->set_doughnut(true);
Series
Series can be defined as a set of values. To set series of a chart, you need to create an instance of chart_series object and pass the title and an array of values.
The title and the data are displayed when mouse over the specific point representing the serie on the chart.
The number of values of the series must be equal to the number of labels.
$serie1 = new core\chart_series('My series title', [400, 460, 1120, 540]);
Properties
Title
It is possible to set a title for a chart, by calling set_title and passing the title as string method.
$chart->set_title('chart with a title');
Labels
Labels are the description in which the data will be grouped, in the example above labels are an array of years. The number of values on the series must match the number of labels.
$chart->set_labels(['2004', '2005', '2006', '2007']);
Axis
Mixed chart types
It is possible to combine two types of chart by setting the type of the series differently of the chart type. For example, to create a chart that combine a bar chart with a line chart:
$chart = new \core\chart_bar(); // Create a bar chart instance.
$series1 = new \core\chart_series('Series 1 (Bar)', [1000, 1170, 660, 1030]);
$series2 = new \core\chart_series('Series 2 (Line)', [400, 460, 1120, 540]);
$series2->set_type(\core\chart_series::TYPE_LINE); // Set the series type to line chart.
$chart->add_series($series2);
$chart->add_series($series1);
$chart->set_labels(['2004', '2005', '2006', '2007']);
Please note the order you call add_series change the order series are displayed on the chart. In the example above, the first to be displayed will be line chart and in the background the bar chart.
Renderering
All charts are rendered by render_chart() located on outputrenderers.php, once the chart object is ready, it must be passed to chart_render. <cide php> echo $OUTPUT->render($chart);
Show chart data
To make the chart data accessible to users with special needs, a link on the bottom of the chart will display a table containing all data.
In some cases, the same information is displayed on the page and might not be necessary display chart table.
In that case, you need to pass false as the second parameter when calling the render:
echo $OUTPUT->render($chart, false);
