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']);

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);