MoodleDocs - User contributions [en]

Output renderers

2015-08-11T01:02:52Z

Aolley: /* Creating a Renderable "widget" in your theme */ Renderable gets passed to the render call

{{Work in progress}}
{{Infobox Project
|name = Output renderers
|state = Implemented
|tracker = MDL-21235
|discussion = n/a
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] + [[User:David Mudrak|David Mudrak]] + feedback and ideas from other developers
}}
{{Moodle 2.0}}

== Goals ==
* stable API
* easy to use
* easy to customise via themes

== Renderers ==

Output renderer is a class with collection of methods that handle rendering of visual aspects of Moodle pages, emails, html export, etc. In Moodle 1.9, general output related functions were located in weblib.php and modules stored rendering code in lib.php, locallib.php, view.php, etc. Output renderer instances are obtained through moodle_page::get_renderer($component, $subtype = null, $target = null) method.

The general renderer class naming convention is:
{theme name}_{plugin type}_{plugin_name}_{subtype}_renderer_{target}

or (if using namespaces)

\{plugin type}_{plugin name}\output\{subtype}_renderer_{target} (standard plugin renderer)

\theme_{theme name}\output\{plugin type}_{plugin name}\{subtype}_renderer_{target} (plugin renderer overridden in a theme)

where theme name prefix, subtype infix and target suffix are optional. Examples of renderer class name are core_renderer, mytheme_core_renderer, mod_workshop_renderer, mod_forum_renderer_cli, \tool_templatelibrary\output\renderer etc.

; Renderer subtype : When get_renderer() is called, $subtype parameter can be provided to obtain a different renderer. Renderer subtypes are used mainly for core subsystems, but it is also possible to use them in modules.

; Renderer targets : In most cases, we are rendering page output for web browsers. Sometimes we need to generate different output for command line scripts, email messages, etc. When get_renderer() is called, $target parameter can be provided to obtain a different renderer. The list of targets will be part of the specification, individual plugins should not invent new rendering targets.

: note that both $subtype and $target works similarly - they just influence the name of the class to be returned by get_renderer(). But there is semantic difference and we will probably have the list of allowed targets limited (defaults to html).

== Overall picture ==

The following UML diagram describes the main classes involved in HTML output rendering and their relationships.

[[Image:uml_output_renderers.png|800px|left]] [[Media:uml_output_renderers.dia|(dia source)]]
<br clear="both" />

=== renderer_base ===

Abstract class every other renderer must extend. Renderer base implements basic methods and support for renderer dispatching.

=== core_renderer ===

Current core_renderer is available through the global $OUTPUT variable. This global should not be used in lower level APIs - only in the main scripts like view.php. When you want to start to print something, you will probably call
echo $OUTPUT->header();
in your view.php or similar script. To print a page footer and terminate your PHP script, you will call
echo $OUTPUT->footer();
die();

Beside these page header and footer related things, core_renderer knows how to display
# boxes and containers - basically <div> elements
# general widgets - headings, single buttons, selection forms, arrows in the breadcrumb navigation, language selection popup, user login info etc.
# error messages, notifications
# blocks

=== method render() and interface renderable ===

Various widgets (headings, buttons etc.) and other content blocks (submissions, forum posts etc.) are represented as classes. In most cases, they will look like a simple object with just some properties and a constructor to set the most common ones. Core renderer implements protected methods to render these widgets. These widget rendering methods are called render_something() where ''something'' is the name of the widget. Their first parameter must be an instance of ''something'' class that implements interface ''renderable''. These methods can be overridden by themes.

Public method to render a widget is called render(). It accepts the only parameter which must be an instance of a class implementing ''renderable'' interface. It uses the class name of the widget passed in as parameter to find the corresponding protected rendering method.

Implementation of renderer_base::render() (inherited by all renderers)
<code php>
class renderer_base {
// ...
public function render(renderable $widget) {
$rendermethod = 'render_'.get_class($widget);
if (method_exists($this, $rendermethod)) {
return $this->$rendermethod($widget);
}
throw new coding_exception('Can not render widget, renderer method ('.$rendermethod.') not found.');
}
// ...
}
</code>

For some widgets, a helper method may be implemented to instantiate the widget and render it in the background. Such helper methods have the same name as the widget class and accepts parameters needed to create the widget instance. Themes should not override helper methods because their usage is optional.

'''Example:''' User avatar rendering involves following methods and classes:
<code php>
class core_renderer extends renderer_base {
// ...
protected function render_user_picture(user_picture $userpicture) {
// returns HTML code to be echoed for displaying the user avatar
}
public function user_picture(stdclass $userrecord, array $options=null) {
// helper method that constructs $user_image widget and calls $this->render()
$picture = new user_picture($userrecord, $options);
return $this->render($picture);
}
// ...
}

class user_picture implements renderable {
public $userrecord;
public $courseid = 0;
public $link = true;

public function __construct(stdclass $userrecord, array $options=null) {
// ...
}
}
</code>

There are two ways how a developer can render the user picture. Either using a one-line style:
<code php>
$user = $DB->get_record('user', array(...));
echo $OUTPUT->user_picture($user, array('courseid' => $courseid, 'link' => true));
</code>

or an explicit stye:
<code php>
$user = $DB->get_record('user', array(...));
$avatar = new user_picture($user);
$avatar->courseid = $courseid;
$avatar->link = true;
echo $OUTPUT->render($avatar);
</code>

The point is that the first style is usually one line only, it is also possible to have multiple helpers with different parameters. The second style allows more options without cluttering the simple API with tons of optional method parameters.

Plugins can also use renderable objects and define render_something() functions in plugin renderers.

=== core_renderer_cli ===

''_cli'' suffix indicates this is a core renderer for CLI rendering target (CLI scripts). For example headings are using '''=>''' instead if H2 html tag.

== Core subsystem renderers ==

== Plugin renderers ==

Plugin renderers are stored in renderer.php file in the same folder as the lib.php file of each plugin. They all extend plugin_renderer_base method.

=== plugin_renderer_base ===

An important thing about this class is that it keeps a reference to an instance of (typically) core_renderer which is used as an underlying renderer. This reference is kept in protected $output member variable. So, there is no more $OUTPUT in plugin renderers. They all use $this->output->something() to render the output.

'''Example:''' Workshop module defines mod_workshop_renderer class in mod/workshop/renderer.php file. The renderer defines a method to display a student submission.
<code php>
// in renderer.php:
class workshop_submission implements renderable {

public function __construct(stdclass $submission, $anonymous = false, array $attachments = null) {
// here the widget is prepared and all necessary logic is performed
if ($anonymous) {
$this->authorname = get_string('anonymousauthor', 'workshop');
} else {
$this->authorname = fullname(...);
}
}
}

class mod_workshop_renderer extends plugin_renderer_base {

protected function render_workshop_submission(workshop_submission $submission) {
$out = $this->output->heading(format_string($submission->title), 2);
$out .= $this->output->container(format_string($submission->authorname), 'author');
$out .= $this->output->container(format_text($submission->content, FORMAT_HTML), 'content');
return $this->output->container($out, 'submission');
}
}

// in view.php
$output = $PAGE->get_renderer('mod_workshop');
$submissionrecord = get_record('workshop_submissions', array(...));
$submissionwidget = new workshop_submission($submissionrecord, false);
echo $output->header();
echo $output->render($submissionwidget);
echo $output->footer();
</code>

Note that $output->header() and $output->footer() are not defined in mod_workshop_renderer. Plugin renderers are able to forward calls to the underlying renderer automatically. So, in view.php, there could be echo $OUTPUT->header(); which would call the same method. We prefer the way above because of consistency - there is the only one $output instance used instead of two $OUTPUT and $wsoutput.

'''WARNING: get_renderer() should typically be the last output related call you make before displaying your page's header.''' get_renderer() forces the page layout to 'base' if it has not already been set and this will almost certainly cause your page to display incorrectly (e.g. no blocks).

Note that as of Moodle 2.9, the render method could be rewritten to use a template. See [[Templates]] for more information.

== Bootstrap renderer ==

Bootstrap renderer is used as a temporary $OUTPUT before the full initialisation of standard core renderer.

== Theme customisations ==

=== Theme renderers ===

Theme renderers are stored in renderers.php file in theme folder (or autoloaded from the classes folder). The actual overriding of renderers is the responsibility of renderer_factory classes which may be selected in theme config.php.

=== Creating a Renderable "widget" in your theme ===

To create a renderable "widget" that could be used in multiple places in your theme (e.g. on the front page, in an overriden renderer for mod_assign etc.)
Create a renderable and renderer in the following folder:
<code>
/theme/mytheme/output/mywidget/rendererable.php
theme/mytheme/output/mywidget/renderer.php
</code>
<code php>
$mywidgetrenderable = new \theme_mytheme\output\mywidget\renderable($params);
$mywidgetrenderer = $this->page->get_renderer('theme_mytheme','mywidget'); // Or $PAGE->get_renderer depending on context
$mywidget = $mywidgetrenderer->render($mywidgetrenderable);
</code>

there is a good example of this in moodle core -> /admin/tool/monitor

== Low level HTML output ==

Low level html markup is created via html_renderer class.

== See also ==
* [[Templates]]
* [[Theme changes]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=177535 Totally confused by output renderers...] forum discussion

[[Category:Themes]]

report/analytics/api

2012-08-16T00:29:48Z

Aolley: /* See also */

{{Moodle_2.2}}This page describes the API used by the Engagement Analytics indicators and reporting mechanisms.

== Main info ==

User documentation here: https://docs.moodle.org/22/en/report/engagement/index

'''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.

Caching of raw data from different indicator plugins is automatically handled by the base indicator class so developers of new indicators don't need to worry about more expensive queries.

==Indicator==

===File Layout===
Indicators live in a folder in <tt>mod/engagement/indicator</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>mod/engagement/indicator/myind</tt> folder we would have:

; indicator.class.php : Defines the <tt>indicator_myind</tt> class, which should extend the <tt>indicator</tt> base class.
; renderer.php : This contains the definition of the <tt>engagementindicator_myind_renderer</tt> class, which should extend the <tt>engagementindicator_renderer</tt> base class.
; thresholds_form.php : Defines the <tt>engagementindicator_myind_thresholds_form</tt> which contains a function <tt>definition_inner</tt> for including on the report settings page.
; lang/en/engagementindicator_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 <tt>$string['pluginname'] = 'My Indicator';</tt>
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|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:
<code php>
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();
</code>

Except for the functions mentioned below, the rest of the ones mentioned above are not generally intended to be overridden in the indicators themselves.

For the development of any new indicator, the functions you '''must''' implement are the abstracted ones:
<code php>
abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);
</code>

The <tt>get_rawdata</tt> function is intended to do the heavy lifting part of the indicator. It'll do the lookups into the database to find out the raw data for the courses users. For example, this collects the counts of read/new/total/replied posts in the forum indicator. This function is called on by the parent class and is put into a cache. The cache has a configurable lifetime set in Site administration / ► Plugins / ► Activity modules / ► Engagement analytics. The setting is <tt>engagement|cachettl</tt> which defaults to 5 minutes. Larger sites may want to consider setting this to a larger number depending on the set of indicators they're using.

The next step in the workflow takes that raw data (which comes from get_cache() unless there's no valid cache entry, which means get_rawdata is called for the data instead) and applies the course specific settings for that indicator. This is done in the <tt>calculate_risks</tt> function. This function will apply the settings set in the report settings page. This allows teachers to update the weightings / thresholds of indicators and see the new risk values without having to refetch raw data every time.

If you have any settings (and most indicators probably will), you'll probably need:
<code php>
protected function load_config();
</code>
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.
<code php>

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

===Helper Functions===

==Indicator Thresholds==

Thresholds and other settings that get applied in the calculate_risks stage can be added to an indicator in the <tt>thresholds_form.php</tt> file.

The settings added to the <tt>definition_inner</tt> function should have a name of the format: "<indicatorname>_<setting>". i.e. for the setting "e_loginsperweek" setting of the "login" indicator, the name would be "login_e_loginsperweek".

===Example===
thresholds_form.php :
<code php>
<?php
defined('MOODLE_INTERNAL') || die();

require_once(dirname(__FILE__).'/../indicator.class.php');
require_once(dirname(__FILE__).'/indicator.class.php');

class engagementindicator_random_thresholds_form {
public function definition_inner(&$mform) {
$defaults = indicator_login::get_defaults();
$mform->addElement('text', 'random_min', get_string('minimum', 'engagementindicator_random'));
$mform->setDefault("random_min", $defaults['min']);

$mform->addElement('text', 'random_max', get_string('maximum', 'engagementindicator_random'));
$mform->setDefault("random_max", $defaults['max']);
}
}
</code>

==Indicator Renderer==

The user report view which lists details from each indicator is defined in an indicators renderer file. If the user_report function is not overridden, the default renderer will simply display the risk score given by that indicator.

===Example===
<code php>
<?php
defined('MOODLE_INTERNAL') || die();

class engagementindicator_random_renderer extends engagementindicator_renderer {
public function user_report($data) {
$html = '';
foreach ($data->info as $i) {
$html .= html_writer::start_tag('strong');
$html .= html_writer::tag('span', $i->title);
$html .= html_writer::end_tag('strong');
$html .= html_writer::empty_tag('br');
$html .= $this->output->help_icon('localrisk', 'engagementindicator_random');
$html .= html_writer::tag('span', 'Local risk: ' . $i->localrisk);
$html .= html_writer::empty_tag('br');
}
return $html;
}

</code>
For the above example to work, the random indicator would need to be returning valid data in the...<TODO>

==See also==
User documentation: https://docs.moodle.org/22/en/report/engagement/index

report/analytics/api

2012-08-16T00:28:47Z

Aolley:

report/analytics/api

2012-08-13T07:27:43Z

Aolley:

{{Moodle_2.2}}This page describes the API used by the Engagement Analytics indicators and reporting mechanisms.

== Main info ==

User documentation here: https://docs.moodle.org/22/en/report/analytics/index

'''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.

Caching of raw data from different indicator plugins is automatically handled by the base indicator class so developers of new indicators don't need to worry about more expensive queries.

==Indicator==

===File Layout===
Indicators live in a folder in <tt>mod/analytics/indicator</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>mod/analytics/indicator/myind</tt> folder we would have:

; indicator.class.php : Defines the <tt>indicator_myind</tt> class, which should extend the <tt>indicator</tt> base class.
; renderer.php : This contains the definition of the <tt>analyticsindicator_myind_renderer</tt> class, which should extend the <tt>analyticsindicator_renderer</tt> base class.
; thresholds_form.php : Defines the <tt>analyticsindicator_myind_thresholds_form</tt> which contains a function <tt>definition_inner</tt> 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 <tt>$string['pluginname'] = 'My Indicator';</tt>
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|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:
<code php>
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();
</code>

Except for the functions mentioned below, the rest of the ones mentioned above are not generally intended to be overridden in the indicators themselves.

For the development of any new indicator, the functions you '''must''' implement are the abstracted ones:
<code php>
abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);
</code>

The <tt>get_rawdata</tt> function is intended to do the heavy lifting part of the indicator. It'll do the lookups into the database to find out the raw data for the courses users. For example, this collects the counts of read/new/total/replied posts in the forum indicator. This function is called on by the parent class and is put into a cache. The cache has a configurable lifetime set in Site administration / ► Plugins / ► Activity modules / ► Engagement analytics. The setting is <tt>analytics|cachettl</tt> which defaults to 5 minutes. Larger sites may want to consider setting this to a larger number depending on the set of indicators they're using.

The next step in the workflow takes that raw data (which comes from get_cache() unless there's no valid cache entry, which means get_rawdata is called for the data instead) and applies the course specific settings for that indicator. This is done in the <tt>calculate_risks</tt> function. This function will apply the settings set in the report settings page. This allows teachers to update the weightings / thresholds of indicators and see the new risk values without having to refetch raw data every time.

If you have any settings (and most indicators probably will), you'll probably need:
<code php>
protected function load_config();
</code>
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.
<code php>

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

===Helper Functions===

==Indicator Thresholds==

Thresholds and other settings that get applied in the calculate_risks stage can be added to an indicator in the <tt>thresholds_form.php</tt> file.

The settings added to the <tt>definition_inner</tt> function should have a name of the format: "<indicatorname>_<setting>". i.e. for the setting "e_loginsperweek" setting of the "login" indicator, the name would be "login_e_loginsperweek".

===Example===
thresholds_form.php :
<code php>
<?php
defined('MOODLE_INTERNAL') || die();

require_once(dirname(__FILE__).'/../indicator.class.php');
require_once(dirname(__FILE__).'/indicator.class.php');

class analyticsindicator_random_thresholds_form {
public function definition_inner(&$mform) {
$defaults = indicator_login::get_defaults();
$mform->addElement('text', 'random_min', get_string('minimum', 'analyticsindicator_random'));
$mform->setDefault("random_min", $defaults['min']);

$mform->addElement('text', 'random_max', get_string('maximum', 'analyticsindicator_random'));
$mform->setDefault("random_max", $defaults['max']);
}
}
</code>

==Indicator Renderer==

The user report view which lists details from each indicator is defined in an indicators renderer file. If the user_report function is not overridden, the default renderer will simply display the risk score given by that indicator.

===Example===
<code php>
<?php
defined('MOODLE_INTERNAL') || die();

class analyticsindicator_random_renderer extends analyticsindicator_renderer {
public function user_report($data) {
$html = '';
foreach ($data->info as $i) {
$html .= html_writer::start_tag('strong');
$html .= html_writer::tag('span', $i->title);
$html .= html_writer::end_tag('strong');
$html .= html_writer::empty_tag('br');
$html .= $this->output->help_icon('localrisk', 'analyticsindicator_random');
$html .= html_writer::tag('span', 'Local risk: ' . $i->localrisk);
$html .= html_writer::empty_tag('br');
}
return $html;
}

</code>
For the above example to work, the random indicator would need to be returning valid data in the...<TODO>

==See also==
User documentation: https://docs.moodle.org/22/en/report/analytics/index

report/analytics/api

2012-08-13T06:54:56Z

Aolley:

{{Moodle_2.2}}This page describes the API used by the Engagement Analytics indicators and reporting mechanisms.

== Main info ==

User documentation here: https://docs.moodle.org/22/en/report/analytics/index

'''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.

Caching of raw data from different indicator plugins is automatically handled by the base indicator class so developers of new indicators don't need to worry about more expensive queries.

==Indicator==

===File Layout===
Indicators live in a folder in <tt>mod/analytics/indicator</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>mod/analytics/indicator/myind</tt> folder we would have:

; indicator.class.php : Defines the <tt>indicator_myind</tt> class, which should extend the <tt>indicator</tt> base class.
; renderer.php : This contains the definition of the <tt>analyticsindicator_myind_renderer</tt> class, which should extend the <tt>analyticsindicator_renderer</tt> base class.
; thresholds_form.php : Defines the <tt>analyticsindicator_myind_thresholds_form</tt> which contains a function <tt>definition_inner</tt> 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 <tt>$string['pluginname'] = 'My Indicator';</tt>
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|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:
<code php>
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();
</code>

Except for the functions mentioned below, the rest of the ones mentioned above are not generally intended to be overridden in the indicators themselves.

For the development of any new indicator, the functions you '''must''' implement are the abstracted ones:
<code php>
abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);
</code>

The <tt>get_rawdata</tt> function is intended to do the heavy lifting part of the indicator. It'll do the lookups into the database to find out the raw data for the courses users. For example, this collects the counts of read/new/total/replied posts in the forum indicator. This function is called on by the parent class and is put into a cache. The cache has a configurable lifetime set in Site administration / ► Plugins / ► Activity modules / ► Engagement analytics. The setting is <tt>analytics|cachettl</tt> which defaults to 5 minutes. Larger sites may want to consider setting this to a larger number depending on the set of indicators they're using.

The next step in the workflow takes that raw data (which comes from get_cache() unless there's no valid cache entry, which means get_rawdata is called for the data instead) and applies the course specific settings for that indicator. This is done in the <tt>calculate_risks</tt> function. This function will apply the settings set in the report settings page. This allows teachers to update the weightings / thresholds of indicators and see the new risk values without having to refetch raw data every time.

If you have any settings (and most indicators probably will), you'll probably need:
<code php>
protected function load_config();
</code>
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.
<code php>

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

===Helper Functions===

==Indicator Thresholds==

Thresholds and other settings that get applied in the calculate_risks stage can be added to an indicator in the <tt>thresholds_form.php</tt> file.

The settings added to the <tt>definition_inner</tt> function should have a name of the format: "<indicatorname>_<setting>". i.e. for the setting "e_loginsperweek" setting of the "login" indicator, the name would be "login_e_loginsperweek".

===Example===
thresholds_form.php :
<code php>
<?php
defined('MOODLE_INTERNAL') || die();

require_once(dirname(__FILE__).'/../indicator.class.php');
require_once(dirname(__FILE__).'/indicator.class.php');

class analyticsindicator_random_thresholds_form {
public function definition_inner(&$mform) {
$defaults = indicator_login::get_defaults();
$mform->addElement('text', 'random_min', get_string('minimum', 'analyticsindicator_random'));
$mform->setDefault("random_min", $defaults['min']);

$mform->addElement('text', 'random_max', get_string('maximum', 'analyticsindicator_random'));
$mform->setDefault("random_max", $defaults['max']);
}
}
</code>

==See also==

report/analytics/api

2012-08-13T05:33:44Z

Aolley: /* Example */

{{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.

Caching of raw data from different indicator plugins is automatically handled by the base indicator class so developers of new indicators don't need to worry about more expensive queries.

==Indicator==

===File Layout===
Indicators live in a folder in <tt>mod/analytics/indicator</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>mod/analytics/indicator/myind</tt> folder we would have:

; indicator.class.php : Defines the <tt>indicator_myind</tt> class, which should extend the <tt>indicator</tt> base class.
; renderer.php : This contains the definition of the <tt>analyticsindicator_myind_renderer</tt> class, which should extend the <tt>analyticsindicator_renderer</tt> base class.
; thresholds_form.php : Defines the <tt>analyticsindicator_myind_thresholds_form</tt> which contains a function <tt>definition_inner</tt> 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 <tt>$string['pluginname'] = 'My Indicator';</tt>
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|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:
<code php>
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();
</code>

Except for the functions mentioned below, the rest of the ones mentioned above are not generally intended to be overridden in the indicators themselves.

For the development of any new indicator, the functions you '''must''' implement are the abstracted ones:
<code php>
abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);
</code>

The <tt>get_rawdata</tt> function is intended to do the heavy lifting part of the indicator. It'll do the lookups into the database to find out the raw data for the courses users. For example, this collects the counts of read/new/total/replied posts in the forum indicator. This function is called on by the parent class and is put into a cache. The cache has a configurable lifetime set in Site administration / ► Plugins / ► Activity modules / ► Engagement analytics. The setting is <tt>analytics|cachettl</tt> which defaults to 5 minutes. Larger sites may want to consider setting this to a larger number depending on the set of indicators they're using.

The next step in the workflow takes that raw data (which comes from get_cache() unless there's no valid cache entry, which means get_rawdata is called for the data instead) and applies the course specific settings for that indicator. This is done in the <tt>calculate_risks</tt> function. This function will apply the settings set in the report settings page. This allows teachers to update the weightings / thresholds of indicators and see the new risk values without having to refetch raw data every time.

If you have any settings (and most indicators probably will), you'll probably need:
<code php>
protected function load_config();
</code>
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.
<code php>

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

===Helper Functions===

==Indicator Thresholds==

Thresholds and other settings that get applied in the calculate_risks stage can be added to an indicator in the <tt>thresholds_form.php</tt> file.

The settings added to the <tt>definition_inner</tt> function should have a name of the format: "<indicatorname>_<setting>". i.e. for the setting "e_loginsperweek" setting of the "login" indicator, the name would be "login_e_loginsperweek".

===Example===
thresholds_form.php :
<code php>
<?php
defined('MOODLE_INTERNAL') || die();

require_once(dirname(__FILE__).'/../indicator.class.php');
require_once(dirname(__FILE__).'/indicator.class.php');

class analyticsindicator_random_thresholds_form {
public function definition_inner(&$mform) {
$defaults = indicator_login::get_defaults();
$mform->addElement('text', 'random_min', get_string('minimum', 'analyticsindicator_random'));
$mform->setDefault("random_min", $defaults['min']);

$mform->addElement('text', 'random_max', get_string('maximum', 'analyticsindicator_random'));
$mform->setDefault("random_max", $defaults['max']);
}
}
</code>

==See also==

report/analytics/api

2012-08-13T05:33:02Z

Aolley:

{{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.

Caching of raw data from different indicator plugins is automatically handled by the base indicator class so developers of new indicators don't need to worry about more expensive queries.

==Indicator==

===File Layout===
Indicators live in a folder in <tt>mod/analytics/indicator</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>mod/analytics/indicator/myind</tt> folder we would have:

; indicator.class.php : Defines the <tt>indicator_myind</tt> class, which should extend the <tt>indicator</tt> base class.
; renderer.php : This contains the definition of the <tt>analyticsindicator_myind_renderer</tt> class, which should extend the <tt>analyticsindicator_renderer</tt> base class.
; thresholds_form.php : Defines the <tt>analyticsindicator_myind_thresholds_form</tt> which contains a function <tt>definition_inner</tt> 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 <tt>$string['pluginname'] = 'My Indicator';</tt>
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|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:
<code php>
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();
</code>

Except for the functions mentioned below, the rest of the ones mentioned above are not generally intended to be overridden in the indicators themselves.

For the development of any new indicator, the functions you '''must''' implement are the abstracted ones:
<code php>
abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);
</code>

The <tt>get_rawdata</tt> function is intended to do the heavy lifting part of the indicator. It'll do the lookups into the database to find out the raw data for the courses users. For example, this collects the counts of read/new/total/replied posts in the forum indicator. This function is called on by the parent class and is put into a cache. The cache has a configurable lifetime set in Site administration / ► Plugins / ► Activity modules / ► Engagement analytics. The setting is <tt>analytics|cachettl</tt> which defaults to 5 minutes. Larger sites may want to consider setting this to a larger number depending on the set of indicators they're using.

The next step in the workflow takes that raw data (which comes from get_cache() unless there's no valid cache entry, which means get_rawdata is called for the data instead) and applies the course specific settings for that indicator. This is done in the <tt>calculate_risks</tt> function. This function will apply the settings set in the report settings page. This allows teachers to update the weightings / thresholds of indicators and see the new risk values without having to refetch raw data every time.

If you have any settings (and most indicators probably will), you'll probably need:
<code php>
protected function load_config();
</code>
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.
<code php>

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

===Helper Functions===

==Indicator Thresholds==

Thresholds and other settings that get applied in the calculate_risks stage can be added to an indicator in the <tt>thresholds_form.php</tt> file.

The settings added to the <tt>definition_inner</tt> function should have a name of the format: "<indicatorname>_<setting>". i.e. for the setting "e_loginsperweek" setting of the "login" indicator, the name would be "login_e_loginsperweek".

===Example===
<code php>
<?php
defined('MOODLE_INTERNAL') || die();

require_once(dirname(__FILE__).'/../indicator.class.php');
require_once(dirname(__FILE__).'/indicator.class.php');

class analyticsindicator_random_thresholds_form {
public function definition_inner(&$mform) {
$defaults = indicator_login::get_defaults();
$mform->addElement('text', 'random_min', get_string('minimum', 'analyticsindicator_random'));
$mform->setDefault("random_min", $defaults['min']);

$mform->addElement('text', 'random_max', get_string('maximum', 'analyticsindicator_random'));
$mform->setDefault("random_max", $defaults['max']);
}
}
</code>

==See also==

report/analytics/api

2012-08-13T05:23:58Z

Aolley: /* Main info */

report/analytics/api

2012-08-13T05:21:19Z

Aolley: /* Functions */

{{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 <tt>mod/analytics/indicator</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>mod/analytics/indicator/myind</tt> folder we would have:

; indicator.class.php : Defines the <tt>indicator_myind</tt> class, which should extend the <tt>indicator</tt> base class.
; renderer.php : This contains the definition of the <tt>analyticsindicator_myind_renderer</tt> class, which should extend the <tt>analyticsindicator_renderer</tt> base class.
; thresholds_form.php : Defines the <tt>analyticsindicator_myind_thresholds_form</tt> which contains a function <tt>definition_inner</tt> 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 <tt>$string['pluginname'] = 'My Indicator';</tt>
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|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:
<code php>
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();
</code>

Except for the functions mentioned below, the rest of the ones mentioned above are not generally intended to be overridden in the indicators themselves.

For the development of any new indicator, the functions you '''must''' implement are the abstracted ones:
<code php>
abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);
</code>

The <tt>get_rawdata</tt> function is intended to do the heavy lifting part of the indicator. It'll do the lookups into the database to find out the raw data for the courses users. For example, this collects the counts of read/new/total/replied posts in the forum indicator. This function is called on by the parent class and is put into a cache. The cache has a configurable lifetime set in Site administration / ► Plugins / ► Activity modules / ► Engagement analytics. The setting is <tt>analytics|cachettl</tt> which defaults to 5 minutes. Larger sites may want to consider setting this to a larger number depending on the set of indicators they're using.

The next step in the workflow takes that raw data (which comes from get_cache() unless there's no valid cache entry, which means get_rawdata is called for the data instead) and applies the course specific settings for that indicator. This is done in the <tt>calculate_risks</tt> function. This function will apply the settings set in the report settings page. This allows teachers to update the weightings / thresholds of indicators and see the new risk values without having to refetch raw data every time.

If you have any settings (and most indicators probably will), you'll probably need:
<code php>
protected function load_config();
</code>
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.
<code php>

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

===Helper Functions===

==See also==

report/analytics/api

2012-08-13T03:09:36Z

Aolley: /* Functions */

report/analytics/api

2012-08-13T03:07:56Z

Aolley: /* Main info */

report/analytics/api

2012-08-13T03:03:21Z

Aolley: /* indicator_random */

{{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 <tt>mod/analytics/indicator</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>mod/analytics/indicator/myind</tt> folder we would have:

; indicator.class.php : Defines the <tt>indicator_myind</tt> class, which should extend the <tt>indicator</tt> base class.
; renderer.php : This contains the definition of the <tt>analyticsindicator_myind_renderer</tt> class, which should extend the <tt>analyticsindicator_renderer</tt> base class.
; thresholds_form.php : Defines the <tt>analyticsindicator_myind_thresholds_form</tt> which contains a function <tt>definition_inner</tt> 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 <tt>$string['pluginname'] = 'My Indicator';</tt>
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|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:
<code php>
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();
</code>

For the development of any new indicator, the functions you '''must''' implement are the abstracted ones:
<code php>
abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);
</code>

If you have any settings (and most indicators probably will), you'll probably need:
<code php>
protected function load_config();
</code>
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.
<code php>

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

===Helper Functions===

==See also==

report/analytics/api

2012-08-13T01:13:12Z

Aolley: Function listing for indicators

{{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 <tt>mod/analytics/indicator</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>mod/analytics/indicator/myind</tt> folder we would have:

; indicator.class.php : Defines the <tt>indicator_myind</tt> class, which should extend the <tt>indicator</tt> base class.
; renderer.php : This contains the definition of the <tt>analyticsindicator_myind_renderer</tt> class, which should extend the <tt>analyticsindicator_renderer</tt> base class.
; thresholds_form.php : Defines the <tt>analyticsindicator_myind_thresholds_form</tt> which contains a function <tt>definition_inner</tt> 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 <tt>$string['pluginname'] = 'My Indicator';</tt>
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|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:
<code php>
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();
</code>

For the development of any new indicator, the functions you '''must''' implement are the abstracted ones:
<code php>
abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);
</code>

If you have any settings (and most indicators probably will), you'll probably need:
<code php>
protected function load_config();
</code>
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.
<code php>

defined('MOODLE_INTERNAL') || die();
require_once(dirname(__FILE__).'/../indicator.class.php');

class indicator_random extends indicator {
protected function get_risk_for_users($userids, $courseid, $startdate, $enddate) {
// TODO: Fill this in.
}

public function get_defaults() {
// TODO: Fill this in.
}

// TODO: Complete class definition.
}
</code>

===Helper Functions===

==See also==

report/analytics/api

2012-08-13T01:05:34Z

Aolley: /* The indicator class */ Add file list for indicators

{{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 <tt>mod/analytics/indicator</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>mod/analytics/indicator/myind</tt> folder we would have:

; indicator.class.php : Defines the <tt>indicator_myind</tt> class, which should extend the <tt>indicator</tt> base class.
; renderer.php : This contains the definition of the <tt>analyticsindicator_myind_renderer</tt> class, which should extend the <tt>analyticsindicator_renderer</tt> base class.
; thresholds_form.php : Defines the <tt>analyticsindicator_myind_thresholds_form</tt> which contains a function <tt>definition_inner</tt> 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 <tt>$string['pluginname'] = 'My Indicator';</tt>
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|as normal]]. See [[#Database_tables]] below.
; db/access.php : Defines any capabilities required by this question type. This is very rarely needed.

===Functions===

===Examples===
====indicator_random====
Return a random risk score for each user.
<code php>

defined('MOODLE_INTERNAL') || die();
require_once(dirname(__FILE__).'/../indicator.class.php');

class indicator_random extends indicator {
protected function get_risk_for_users($userids, $courseid, $startdate, $enddate) {
// TODO: Fill this in.
}

public function get_defaults() {
// TODO: Fill this in.
}

// TODO: Complete class definition.
}
</code>

===Helper Functions===

==See also==

report/analytics/api

2012-08-01T03:28:47Z

Aolley: Bare bones entry

{{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 class ==

===Functions===

===Examples===
====indicator_random====
Return a random risk score for each user.
<code php>

defined('MOODLE_INTERNAL') || die();
require_once(dirname(__FILE__).'/../indicator.class.php');

class indicator_random extends indicator {
protected function get_risk_for_users($userids, $courseid, $startdate, $enddate) {
// TODO: Fill this in.
}

public function get_defaults() {
// TODO: Fill this in.
}

// TODO: Complete class definition.
}
</code>

===Helper Functions===

==See also==

Data manipulation API

2012-08-01T03:27:58Z

Aolley: Undo revision 34607 by Aolley (talk)

{{Moodle_2.0}}This page describes the functions available to access data in the Moodle database. You should '''exclusively''' use these functions in order to retrieve or modify database content because these functions provide a high level of abstraction and guarantee that your database manipulation will work against different RDBMSes.

Where possible, tricks and examples will be documented here in order to make developers' lives a bit easier. Of course, feel free to clarify, complete and add more information to this documentation. It will be welcome, absolutely!

== Main info ==

'''Important note:''' All the functions shown on this page are for use in '''Moodle 2.0 upwards''', where we changed the [[DB layer 2.0|DB layer]] to support some new features. If you need information for previous Moodle version, take a look to the [[DML functions - pre 2.0|DML functions - pre 2.0]] page. For a detailed reference of changes, see the [[DB layer 2.0 migration docs|migration docs]].

* All the function calls on this page are public methods of the $DB global object, so you'll need to "import" it within your functions (not needed in global scripts) with one simple:
<code php>global $DB;</code>
* The $DB global object is an instance of the moodle_database class, which is defined in [http://cvs.moodle.org/moodle/lib/dml/moodle_database.php?view=markup moodle_database.php]
* All the $table parameters in the functions are meant to be the table name ''without'' prefixes.
<code php>$user = $DB->get_record('user', array('id'=>'1');</code>
* When using the xxx_sql() functions, table names must be enclosed between curly braces.
<code php>$user = $DB->get_record_sql('SELECT * FROM {user} WHERE id = ?', array(1));</code>
* All the $conditions parameters in the functions are arrays of fieldname=>fieldvalue elements.
<code php>$user = $DB->get_record('user', array('firstname'=>'Martin', 'lastname'=>'Dougiamas'));</code>
* All the $params parameters in the functions are arrays of values used to fill placeholders in SQL statements. Both the question mark and named placeholders can be used. Note that named params '''must be unique''' even if the value passed is the same.
<code php>
/// Question mark placeholders:
$DB->get_record_sql('SELECT * FROM {user} WHERE firstname = ? AND lastname = ?',
array('Martin', 'Dougiamas'));

/// Named placeholders:
$DB->get_record_sql('SELECT * FROM {user} WHERE firstname = :firstname AND lastname = :lastname',
array('firstname'=>'Martin', 'lastname'=>'Dougiamas'));
</code>

== The functions ==

===Getting a single record===

<code php>
o $DB->get_record($table, array $conditions, $fields='*', $strictness=IGNORE_MISSING)
/// Get a single database record as an object where all the given conditions met.
/// @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
/// IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
/// MUST_EXIST means throw exception if no record or multiple records found
o $DB->get_record_select($table, $select, array $params=null, $fields='*', $strictness=IGNORE_MISSING)
/// Get a single database record as an object which match a particular WHERE clause.
o $DB->get_record_sql($sql, array $params=null, $strictness=IGNORE_MISSING)
/// Get a single database record as an object using a SQL statement.
</code>

===Getting an hashed array of records===
Each of the following methods return an array of objects. The array is indexed by the first column of the fields returned by the query. Thus to assure consistent data, it appears to be best practice to ensure that your query include an "id column" as the first field. (When developing custom tables, be sure to make id your first column for this reason!)
<code php>
o $DB->get_records($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects where all the given conditions met.
o $DB->get_records_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects which match a particular WHERE clause.
o $DB->get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects using a SQL statement.
o $DB->get_records_list($table, $field, array $values, $sort='', $fields='*', $limitfrom='', $limitnum='')
/// Get a number of records as an array of objects where one field match one list of values.
</code>

===Getting an
The following methods return data as key/value pairs in an associative array.
<code php>
o $DB->get_records_menu($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array where all the given conditions met.
o $DB->get_records_select_menu($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array which match a particular WHERE clause.
o $DB->get_records_sql_menu($sql, array $params=null, $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array using a SQL statement.
</code>

===Seeing how many records match a given criteria===
<code php>
o $DB->count_records($table, array $conditions=null)
/// Count the records in a table where all the given conditions met.
o $DB->count_records_select($table, $select, array $params=null, $countitem="COUNT('x')")
/// Count the records in a table which match a particular WHERE clause.
o $DB->count_records_sql($sql, array $params=null)
/// Get the result of a SQL SELECT COUNT(...) query.
</code>

===Seeing if one record exists===
<code php>
o $DB->record_exists($table, array $conditions=null)
/// Test whether a record exists in a table where all the given conditions met.
o $DB->record_exists_select($table, $select, array $params=null)
/// Test whether any records exists in a table which match a particular WHERE clause.
o $DB->record_exists_sql($sql, array $params=null)
/// Test whether a SQL SELECT statement returns any records.
</code>

====Examples====
=====moodle_database::get_records()=====
Get a number of records as an array of objects where all the given conditions met.
<code php>
///Get all records where foo = bar
$result = $DB->get_records($table,array('foo'=>'bar'));

///Get all records where foo = bar and jon = doe
$result = $DB->get_records($table,array('foo' => 'bar' , 'jon' => 'doe'));

///Get all records where foo = bar, but only return the fields foo,bar,jon,doe
$result = $DB->get_records($table,array('foo'=>'bar'),null,'foo,bar,jon,doe');
///The previous example would cause data issues unless the 'foo' field happens to have unique values.
</code>

=====moodle_database::get_records_select()=====
Get a number of records as an array of objects which match a particular WHERE clause.
<code php>
///Get all records where jon = 'doe' and bob is not = 'tom'
///The 'select' parameter is (if not empty) is dropped directly into the WHERE clause without alteration.
$table = 'foo';
$select = "jon = 'doe' AND bob <> 'tom'"; //is put into the where clause
$result = $DB->get_records_select($table,$select);
</code>

=====moodle_database::get_records_sql()=====
Get a number of records as an array of objects using a SQL statement. Defined as an abstract function in moodle_database, this method is implemented per database type.
<code php>
///Get all records from 'table' where foo = bar
$result = $DB->get_records_sql('SELECT * FROM {table} WHERE foo = ?', array('bar'));

///Get all records from 'table' where foo = 'bar' and bob = 'tom'
///This is somewhat similar to how Drupal makes its queries
$result = $DB->get_records_sql('SELECT * FROM {table} WHERE foo = ? AND bob = ?', array( 'bar' , 'tom' ));
</code>

=====moodle_database::get_records_list()=====
Get a number of records as an array of objects where one field match one list of values.
<code php>
///Get all records where the values('bar', 'elephant', 'moodle') are found in the field 'foo'
$result = $DB->get_records_list($table, 'foo', array( 'bar', 'elephant', 'moodle'));

///Get all records where the values('bar', 'elephant', 'moodle') are found in the field 'foo'
///Only returning the fields 'id', 'test' and 'taco'
$result = $DB->get_records_list($table, 'foo', array( 'bar', 'elephant', 'moodle'), null, 'id,test,taco');
</code>

=====moodle_database::get_records_menu()=====
Get the first two columns from a number of records as an associative array where all the given conditions met.
You can choose the two fields or leave the parameter blank and the method will return the first two columns of the table.
Returns an associative array.
<code php>
///Get all records from table 'foo' where column 'foo' is equal to the value 'bar'
$table = 'foo'; ///name of table
$conditions = array('foo'=>'bar'); ///the name of the field (key) and the desired value

$result = $DB->get_records_menu($table,$conditions));

///Get all records from table 'foo' where column 'foo' is equal to the value 'bar'
///Returning the values from the columns 'id' and 'tacos'
$table = 'foo'; ///name of table
$conditions = array('foo'=>'bar'); ///the name of the field (key) and the desired value
$sort = 'id'; //field or fields you want to sort the result by
$fields = 'id, tacos'; ///list of fields to return

$result = $DB->get_records_menu($table,$conditions,$sort,$fields)); //If you do not specify $fields, the first two columns of the table will be returned

</code>
The result of this last example will look something like:
<code php>
/// The value of the id field is 909 and the value of the 'tacos' column is 6
array(1) { [909]=6 }
</code>

=====moodle_database::get_records_select_menu()=====
Get the first two columns from a number of records as an associative array which match a particular WHERE clause.
<code php>
///Get all records where jon = 'doe' and bob is not = 'tom'
///The 'select' parameter is (if not empty) is dropped directly into the WHERE clause without alteration.
$table = 'foo';
$select = 'jon = "doe" AND bob != "tom" '; //is put into the where clause
$result = $DB->get_records_select_menu($table,$select);

$table = 'foo';
$select = 'jon = "doe" AND bob != "tom" '; //is put into the where clause
$fields = 'id, tacos';//return these fields
$sort = 'id'; //field or fields you want to sort the result by
$result = $DB->get_records_select_menu($table,$select,null,$sort,$fields);
</code>

The result of this last example will look something like:
<code php>
/// The value of the id field is 909 and the value of the 'tacos' column is 6
array(1) { [909]=6 }
</code>

=====moodle_database::get_records_sql_menu()=====
Get the first two columns from a number of records as an associative array using a SQL statement.
<code php>
///Get all records from table foo where bar = 6
$sql = 'SELECT * FROM foo WHERE bar = ?';
$params = array(6);

$result = $DB->get_records_sql_menu($sql,$params);

///Get all records from table foo where bar = 6
$sql = 'SELECT id,tacos FROM foo WHERE bar = ?';
$params = array(6);

$result = $DB->get_records_sql_menu($sql,$params);

</code>

The result of this last example will look something like:
<code php>
/// The value of the id field is 909 and the value of the 'tacos' column is 6
array(1) { [909]=6 }
</code>

===Getting a particular field value from one record===
<code php>
o $DB->get_field($table, $return, array $conditions, $strictness=IGNORE_MISSING)
/// Get a single field value from a table record where all the given conditions met.
/// @param int $strictness
/// IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
/// IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
/// MUST_EXIST means throw exception if no record or multiple records found
o $DB->get_field_select($table, $return, $select, array $params=null, $strictness=IGNORE_MISSING)
/// Get a single field value from a table record which match a particular WHERE clause.
o $DB->get_field_sql($sql, array $params=null, $strictness=IGNORE_MISSING)
/// Get a single field value (first field) using a SQL statement.
</code>

===Getting a particular field value from various records===

<code php>
o $DB->get_fieldset_select($table, $return, $select, array $params=null)
/// Selects records and return values of chosen field as an array which match a particular WHERE clause.
o $DB->get_fieldset_sql($sql, array $params=null)
/// Selects records and return values (first field) as an array using a SQL statement.
</code>

===Setting a particular field in the database===
<code php>
o $DB->set_field($table, $newfield, $newvalue, array $conditions=null)
/// Set a single field in every table record where all the given conditions met.
o $DB->set_field_select($table, $newfield, $newvalue, $select, array $params=null)
/// Set a single field in every table record which match a particular WHERE clause.
</code>

===Deleting Records===
<code php>
o $DB->delete_records($table, array $conditions=null)
/// Delete the records from a table where all the given conditions met.
o $DB->delete_records_select($table, $select, array $params=null)
/// Delete one or more records from a table which match a particular WHERE clause.
</code>

===Inserting Records===
The method to insert records is called aptly enough, insert_record(). The method accepts 4 parameters, but the fourth, "bulk", in most implementations is unused.
<code php>
o $DB->insert_record($table, $dataobject, $returnid=true, $bulk=false)
/// Insert a record into a table and return the "id" field if required.
</code>
====Example(s)====
<code php>
$record = new stdClass();
$record->name = 'overview';
$record->displayorder = '10000';
$DB->insert_record('quiz_report', $record, false);
</code>

<code php>
$record = new stdClass();
$record->name = 'overview';
$record->displayorder = '10000';
$lastinsertid = $DB->insert_record('quiz_report', $record);
</code>

===Updating Records===
<code php>
o $DB->update_record($table, $dataobject, $bulk=false)
/// Update a record in a table.
///
/// $dataobject is an object containing needed data
/// Relies on $dataobject having a variable "id" to
/// specify the record to update
///
/// @param string $table The database table to be checked against.
/// @param object $dataobject An object with contents equal to fieldname=>fieldvalue.
/// Must have an entry for 'id' to map to the table specified.
/// @param bool $bulk true means repeated updates expected
/// @return bool true
/// @throws dml_exception if an error occurs.
</code>

===Using Recordsets===

Where the number of records to be retrieved from DB is high, the '''get_records_xxx()''' functions above are far from optimal, because they load all the records in memory at the same time. Under those circumstances, it is highly recommended to use these '''get_recordset_xxx()''' functions instead, which use one nice mechanism to iterate over all the target records and save a lot of memory.

Only one thing is '''absolutely important''': Don't forget to close the recordsets after using them! (This will free up a lot of resources in the RDBMS).

Here is the general way to iterate over records using the '''get_recordset_xxx()''' functions:

<code php>
$rs = $DB->get_recordset(....) {
foreach ($rs as $record) {
// Do whatever you want with this record
}
$rs->close(); // Don't forget to close the recordset!
</code>

And this is the list of available functions (100% paired with the get_records_xxx() above):
<code php>
o $DB->get_recordset($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as a moodle_recordset where all the given conditions met.
o $DB->get_recordset_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as a moodle_recordset which match a particular WHERE clause.
o $DB->get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0);
/// Get a number of records as a moodle_recordset using a SQL statement.

o $DB->get_recordset_list($table, $field='', $values='', $sort='', $fields='*', $limitfrom='', $limitnum='')
/// Get a number of records as a moodle_recordset where one field matches one list of values.
</code>

Unlike get_record functions, you cannot use <tt>$rs == true</tt> or <tt>!empty($rs)</tt> to determine if any records were found.
Recordsets implement the standard PHP Iterator interface (http://uk.php.net/manual/en/class.iterator.php)

So,
<code php>
if ($rs->valid()) {
// The recordset contains records.
}
</code>

===Delegated transactions===

* Please note some databases do not support transactions (such as the MyISAM MySQL database engine), however all server administrators are strongly encouraged to migrate to databases that support transactions (such as the InnoDB MySQL database engine).
* Previous versions supported only one level of transaction. Since Moodle 2.0, the DML layer emulates delegated transactions that allow nesting of transactions.
* Transactions should not be used much in Moodle core; they are intended for various plugins such as web services, enrol and auth plugins.
* Some subsystems (such as messaging) do not support transactions because is it is not possible to rollback in external systems.

A transaction is started by:
<code php>
$transaction = $DB->start_delegated_transaction();
</code>

and finished by:
<code php>
$transaction->allow_commit();
</code>

Usually a transaction is rolled back when an exception is thrown. <code>$transaction->rollback($ex);</code> must be used very carefully because it might break compatibility with databases that do not support transactions. Transactions cannot be used as part of expected code flow; they can be used only as an emergency protection of data consistency.

See more details in [[DB layer 2.0 delegated transactions]] or MDL-20625.

====Example(s)====

<code php>
global $DB;
try {
$transaction = $DB->start_delegated_transaction();
// Insert a record
$DB->insert('foo', $object);
$DB->insert('bar', $otherobject);

// Assuming the both inserts work, we get to the following line.
$transaction->allow_commit();
} catch(Exception $e) {
$transaction->rollback($e);
}
</code>

===Helper Functions===

In order have real cross-db compatibility, there are some helper functions used to build SQL fragments based on the DB Moodle is running. Using them we'll avoid conditional queries here and there and have those "incompatibilities" fixed once and for ever.
<code php>
o $DB->sql_bitand($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise AND
/// operation between 2 integers.
o $DB->sql_bitnot($int1)
/// Returns the SQL text to be used in order to perform one bitwise NOT
/// operation with 1 integer.
o $DB->sql_bitor($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise OR
/// operation between 2 integers.
o $DB->sql_bitxor($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise XOR
/// operation between 2 integers.

o $DB->sql_null_from_clause()
/// Returns the FROM clause required by some DBs in all SELECT statements.

o $DB->sql_ceil($fieldname)
/// Returns the correct CEIL expression applied to fieldname.
o $DB->sql_like($fieldname, $param, $casesensitive = true, $accentsensitive = true, $notlike = false, $escapechar = ' \\ ')
/// Returns the proper SQL to do LIKE. For example:
$DB->get_records_sql('SELECT ... WHERE '.$DB->sql_like('idnumber', ':idnum').' ... ', array( 'idnum' => 'foo'));

o $DB->sql_length($fieldname)
/// Returns the SQL text to be used to calculate the length in characters of one expression.
o $DB->sql_modulo($int1, $int2)
/// Returns the SQL text to be used in order to calculate module - remainder after division
o $DB->sql_position($needle, $haystack)
/// Returns the SQL for returning searching one string for the location of another.
/// Note: If using placeholders BOTH in $needle and $haystack, they MUST be named placeholders.
o $DB->sql_substr($expr, $start, $length=false)
/// Returns the proper substr() SQL text used to extract substrings from DB.
/// Note: This fuction has changed in Moodle 2.0 and now at least 2 params are mandatory.
/// Note: Now it returns the whole SQL text to be used instead of only the function name.

o $DB->sql_cast_char2int($fieldname, $text=false)
/// Returns the SQL to be used in order to CAST one CHAR column to INTEGER.
o $DB->sql_cast_char2real($fieldname, $text=false)
/// Returns the SQL to be used in order to CAST one CHAR column to REAL number.

o $DB->sql_compare_text($fieldname, $numchars=32)
/// Returns the SQL text to be used to compare one TEXT (clob) column.
/// with one VARCHAR column.
o $DB->sql_order_by_text($fieldname, $numchars=32)
/// Returns the SQL text to be used to order by one TEXT (clob) column.

o $DB->sql_concat()
/// Returns the proper SQL to do CONCAT between the elements passed.
o $DB->sql_concat_join($separator="' '", $elements=array())
/// Returns the proper SQL to do CONCAT between the elements passed using one separator.
o $DB->sql_fullname($first='firstname', $last='lastname')
/// Returns the proper SQL to concatenate $firstname and $lastname.

o $DB->sql_isempty($tablename, $fieldname, $nullablefield, $textfield)
/// Returns the proper SQL to know if one field is empty.
o $DB->sql_isnotempty($tablename, $fieldname, $nullablefield, $textfield)
/// Returns the proper SQL to know if one field is not empty.
o $DB->sql_empty()
/// Returns the empty string char used by every supported DB.
</code>

==See also==

* [[Core APIs]]
* [[DML exceptions|DML exceptions]]: New DML code is throwing exceptions instead of returning false if anything goes wrong
* [[DML drivers|DML drivers]]: Database drivers for new DML layer
* [[DML functions - pre 2.0|DML functions - pre 2.0]]: '''(deprecated!)''' For information valid before Moodle 2.0.
* [[DDL functions|DDL functions]]: Where all the functions used to handle DB objects ([[wikipedia:Data_Definition_Language|DDL]]) are defined.
* [[DB layer 2.0 examples|DB layer 2.0 examples]]: To see some code examples using various DML functions.
* [[DB layer 2.0 migration docs|DB layer 2.0 migration docs]]: Information about how to modify your code to work with the new Moodle 2.0 DB layer.
* [[DTL functions|DTL functions]]: Exporting, importing and moving of data stored in SQL databases

[[Category:DB]]
[[Category:XMLDB]]
[[Category:API]]

Data manipulation API

2012-08-01T03:27:30Z

Aolley: Bare bones entry

{{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 class ==

===Functions===

===Examples===
====indicator_random====
Return a random risk score for each user.
<code php>

defined('MOODLE_INTERNAL') || die();
require_once(dirname(__FILE__).'/../indicator.class.php');

class indicator_random extends indicator {
protected function get_risk_for_users($userids, $courseid, $startdate, $enddate) {
// TODO: Fill this in.
}

public function get_defaults() {
// TODO: Fill this in.
}

// TODO: Complete class definition.
}
</code>

===Helper Functions===

==See also==