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!

The indicator's used by this plugin have been designed as sub-plugins to allow (and encourage) other developers to create their own indicators. Indicators could be developed to report on a wide range of things inside Moodle or even collect data from external systems to report on if desired.

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

}