report/analytics/api

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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

}

Documentation