report/analytics/api
Moodle 2.2 This page describes the API used by the Engagement Analytics indicators and reporting mechanisms.
Main info
IMPORTANT This page is a WIP and does not reflect the final state of the engagement analytics API!
Indicator
File Layout
Indicators live in a folder in mod/analytics/indicator. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the mod/analytics/indicator/myind folder we would have:
- indicator.class.php
- Defines the indicator_myind class, which should extend the indicator base class.
- renderer.php
- This contains the definition of the analyticsindicator_myind_renderer class, which should extend the analyticsindicator_renderer base class.
- thresholds_form.php
- Defines the analyticsindicator_myind_thresholds_form which contains a function definition_inner for including on the report settings page.
- lang/en/analyticsindicator_myind.php
- English language strings for this indicator. You can, of course, include other languages too. The language file must define at least the string giving the indicator a name, for example $string['pluginname'] = 'My Indicator';
- db/install.xml, db/upgrade.php
- For creating any database tables required, as normal. See #Database_tables below.
- db/access.php
- Defines any capabilities required by this question type. This is very rarely needed.
Functions
The indicator base class defines the following functions:
public function get_risk($userid, $courseid, $startdate = null, $enddate = null);
public function get_course_risks($startdate = null, $enddate = null);
private function get_risk_for_users($userids, $startdate, $enddate);
final private function get_cache();
final private function set_cache();
abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);
public function get_name();
protected function load_config();
public function save_config();
For the development of any new indicator, the functions you must implement are the abstracted ones:
abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);
If you have any settings (and most indicators probably will), you'll probably need:
protected function load_config();
Which can be used to setup any default values you need for when a user hasn't input any on their own.
Examples
indicator_random
Return a random risk score for each user.
defined('MOODLE_INTERNAL') || die();
require_once(dirname(__FILE__).'/../indicator.class.php');
class indicator_random extends indicator {
protected function get_rawdata($startdate, $enddate) {
global $DB;
$rawdata = array();
$someusers = get_enrolled_users($this->context);
foreach ($someusers as $user) {
$rawdata[$user->id] = mt_rand(0,100);
}
return $rawdata;
}
protected function calculate_risks(array $userids) {
$risks = array();
foreach ($userids as $userid) {
if (!isset($this->rawdata[$userid])) {
$risk = new stdClass();
$risk->risk = 0;
$risk->info = 'No risk, user had no data collected.';
$risks[$userid] = $risk;
}
$risk = new stdClass();
$value = $this->rawdata[$userid];
if ($value > $this->config['max']) {
$value = $this->config['max'];
} else if ($value < $this->config['min']) {
$value = $this->config['min'];
}
$risk->risk = $value;
$risk->info = 'Random risk calcualted.';
$risks[$userid] = $risk;
}
return $risks;
}
protected function load_config() {
parent::load_config();
$defaults = $this->get_defaults();
foreach ($defaults as $setting => $value) {
if (!isset($this->config[$setting])) {
$this->config[$setting] = $value;
}
}
}
public function get_defaults() {
$defaults = array();
$defaults['min'] = 5;
$defaults['max'] = 20;
return $defaults;
}
}