reportbuilder/API
Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.
Overview
Report builder provides an interface to allow administrators to generate reports, customise their appearance, then make them available to groups of users. It is designed to be easily extensible, so developers can add to existing report sources and write their own to allow administrators to generate the kind of reports they are interested in.
The report builder API enables plugin contributors and moodle core developers to create new sources that can be used by site administrators and teachers to generate and customise reports.
How to create a source
Sources should have the namespace with the Frankenstyle prefix of the module, followed by rb_source, and then the name of the source. (e.g. mod_assign\rb_source\submission). It should be located in the module's classes folder, in the source subfolder. (e.g. mod/assign/classes/rb_source/submission.php)
The class must be a child of report_builder_source_base.
The following is an example of a Report Builder source:
<?php
class report_builder\rb_source\course extends report_builder\rb_source\base {
public $base, $joinlist, $columnoptions, $filteroptions;
function __construct() {
$this->base = '{course}';
$this->joinlist = array(
new rb_join(
'course_category',
'LEFT',
'{course_categories}',
'course_category.id = base.category'
)
);
$this->columnoptions = array(
new rb_column_option(
'course',
'fullname',
'Course Fullname',
'base.fullname'
),
new rb_column_option(
'course_category',
'name',
'Course Fullname',
'course_categories.name'
array('joins' => 'course_categories')
)
);
$this->filteroptions = array();
$this->sourcetitle = "Courses";
parent::__construct();
}
}
A source consists of:
- A base table: base (Defines what table all reports from this source will be based off)
- A join list: joinlist (Defines what tables should be joined to the base table)
- Column options: columnoptions (Defines which columns from each table should be available in the report)
- Filter options: filteroptions (Defines what fields can be used to filter the results in the report)
- Default columns: defaultcolumns (Defines what fields will be selected when a report is first created from this source)
- Default filters: defaultfilters (Defines what filters will be available when a report is first created from this source)
When using collumns from a joined table, the rb_column_option should include "joins" in the fifth parameter.
new rb_column_option(
'course_category',
'name',
'Course Fullname',
'course_categories.name'
array('joins' => 'course_categories')
)
Helper Functions
A number of helper functions exist that can be used to aid the creation of a source. For instance, 'add_user_table_to_joinlist' can be used to join the user table, 'add_user_fields_to_columns' can be used to add the columns, and 'add_user_fields_to_filters' can be used to add the filters.
Example:
$this->add_user_table_to_joinlist($joinlist_array, 'base', 'userid'); // Where 'base' is the name of the joined table with the users' ids, and 'userid' is the name of the column. $this->add_user_fields_to_columns($columnoptions_array); $this->add_user_fields_to_filters($filteroptions_array) $this->joinlist = $joinlist_array; $this->columnoptions = $columnoptions_array; $this->filteroptions = $filteroptions_array;
Below is an example of a source for the activity module "Choice". Please note that it is written to work with current code.
defined('MOODLE_INTERNAL') || die();
class rb_source_choice extends rb_base_source {
/**
* Constructor for defining a report builder source object.
*/
function __construct() {
$this->base = '{choice_answers}';
$this->joinlist = $this->define_joinlist();
$this->columnoptions = $this->define_columnoptions();
$this->filteroptions = $this->define_filteroptions();
$this->defaultcolumns = $this->define_defaultcolumns();
$this->sourcetitle = get_string('choice', 'mod_choice');
parent::__construct();
}
The constructor defines the basic structure of the source. It is possible to define all the information in this method, but this quickly become large and unwieldy. The main table (base) for this report source is choice_answers.
/**
* Other tables that are related to this source.
*
* @return array An array of rb_join objects.
*/
protected function define_joinlist() {
$joinlist = array(
new rb_join(
'choiceoptions',
'LEFT',
'{choice_options}',
'choiceoptions.id = base.optionid'
),
new rb_join(
'choice',
'LEFT',
'{choice}',
'choice.id = base.choiceid'
)
);
$this->add_user_table_to_joinlist($joinlist, 'base', 'userid');
return $joinlist;
}
In this section of the code we have defined all of the possible other tables that will link with the base one. The rb_join object in this example has four properties.
- This is the table alias.
- What type of join is being used.
- The table name.
- sql join code.
/**
* Columns that can be selected in this report.
*
* @return array An array of rb_columnoptions.
*/
protected function define_columnoptions() {
$columnoptions = array(
new rb_column_option(
'choice',
'title',
'Name',
'choice.name',
array('joins' => 'choice')
),
new rb_column_option(
'choice',
'choiceoption',
get_string('choicename', 'mod_choice'),
'choiceoptions.text',
array('joins' => 'choiceoptions')
),
new rb_column_option(
'choice',
'timemodified',
'Time modified',
'base.timemodified',
array(
'displayfunc' => 'nice_datetime'
)
)
);
$this->add_user_fields_to_columns($columnoptions);
return $columnoptions;
}
/**
* Filters that can be added to this report.
*
* @return array An array of rb_filter_option objects.
*/
protected function define_filteroptions() {
$filteroptions = array(
new rb_filter_option(
'choice',
'choiceoption',
get_string('choicename', 'mod_choice'),
'select',
array('selectfunc' => 'choice_option_list')
)
);
$this->add_user_fields_to_filters($filteroptions);
return $filteroptions;
}
/**
* Defines the default columns when creating a report.
*
* @return array An array of default columns.
*/
protected function define_defaultcolumns() {
$defaultcolumns = array(
array(
'type' => 'user',
'value' => 'namelink'
),
array(
'type' => 'choice',
'value' => 'title'
)
);
return $defaultcolumns;
}
/**
* Custom function to return an array of choice options.
*
* @return array Choice options.
*/
function rb_filter_choice_option_list() {
global $DB;
$choiceoptions = array();
$records = $DB->get_records_sql("SELECT text FROM {choice_options}");
foreach ($records as $value) {
$choiceoptions[$value->text] = $value->text;
}
return $choiceoptions;
}
