MoodleDocs - User contributions [en]

Time API

2020-05-21T12:58:41Z

Davidbalch: /* Examples */

==Overview==

Internally Moodle always stores all times in unixtime format (number of seconds since epoch) which is independent of timezones.

The Time API is used to display proper date-time depending on user or site timezones.

==Functions==
There is a class in Moodle to handle most needs of working with times. There are 2 cases to consider when working with time:

System Time

This is when you are dealing with dates on the server e.g. executing scheduled tasks, performing background tasks - anything which does not depend on the timezone of any specific user.

User Time

This is when you are manipulating dates and times and you need to display them to the user in their current timezone (which may be different for each user).

The main API for time is in the class "core_date" which will give you php DateTimeZone objects for either user time or server time as needed. You can then use the php datetime classes to manipulate the time. When finished manipulating the time, get a timestamp with DateTime::getTimestamp().

Example: Get the current server time + 1 day.

<code>
$tomorrow = new DateTime("1 day", core_date::get_server_timezone_object());
</code>

Get a timestamp for storing in the database:
<code>
$tomorrowint = $tomorrow->getTimestamp();
</code>

Get a timestamp for 3pm tomorrow in the current users timezone.

<code>
$time = new DateTime("now", core_date::get_user_timezone_object());
$time->add(new DateInterval("P1D"));
$time->setTime(15, 0, 0);

$timestamp = $time->getTimestamp();
</code>

Remember! NEVER NEVER NEVER add or subtract timestamps for any reason - you will get it wrong (DST is a killer)!

Other functions related to time api can be found in lib/moodlelib.php.
# Time API's for current user
#* '''make_timestamp''' - Given date-time, it produces a GMT timestamp for current user.
#* '''userdate''' - Gets formatted string that represents a date in user time (note that the format required by this function is the [https://www.php.net/manual/en/function.strftime.php strftime()] format, not the more common format used by date())
#* '''usertime''' - Given a GMT timestamp (seconds since epoch), offsets it by the timezone. eg 3pm in India is 3pm GMT - 5.5 * 3600 seconds
#* '''usergetdate''' - Given a timestamp in GMT, returns an array that represents the date-time in user time
#* '''usergetmidnight''' - Given a date, return the GMT timestamp of the most recent midnight for the current user.
#* '''usertimezone''' - Returns current user's timezone

# System Time API
#* '''format_time''' - Format a date/time (seconds) as weeks, days, hours etc as needed
#* '''dst_offset_on''' - Calculates the Daylight Saving Offset for a given date/time (timestamp)
#* '''find_day_in_month''' - Calculates when the day appears in specific month
#* '''days_in_month''' - Calculate number of days in a given month
#* '''dayofweek''' - Calculate the position in the week of a specific calendar day

# Older legacy date/time functions. Do not use in new code.
#* '''usertime''' - Appends the users timezone offset to an integer timestamp
#* '''get_timezone_offset''' - Systems's timezone difference from GMT in seconds
#* '''get_user_timezone_offset''' - Returns user's timezone difference from GMT in hours
#* '''dst_changes_for_year''' - Calculates the required DST change and returns a Timestamp Array

==Glossary==
===Timezone===
Moodle supports following timezone formats:
# UTC (specifically UTC−11 to UTC+11)
# Time offsets from UTC (int +-(0-13) or float +-(0.5-12.5))
# World timezones (Australia/Perth)

===Location===
Timezone depends on [[:en:Location]] of the user and can be forced upon by administrator.
===DST===
DST is abbreviation of '''Daylight Saving Time''' (also known as "Day light saving" and "Summer Time"). Many countries, and sometimes just certain regions of countries, adopt daylight saving time during part of the year. Moodle automatically calculates DST for current user, depending on user location.

==Examples==
===Create DateTime with date/time from a unixtime (number of seconds)===

$date = new DateTime();
$date->setTimestamp(intval($unixtime);
echo userdate($date->getTimestamp());

===Time API's for current user===
Prints a formatted date in user time
<pre>
// Get current day, month and year for current user.
$date = new DateTime("now", core_date::get_user_timezone_object());
$date->setTime(0, 0, 0);
// Print formatted date in user time.
echo userdate($date->getTimestamp(), "Current user time");
</pre>

===System Time API===
Find the day of the week for the first day in this month.

<pre>
$now = new DateTime("now", core_date::get_server_timezone_object());

$year = $now->format('Y');
$month = $now->format('m');

$now->setDate($year, $month, 1);
$dayofweek = $now->format('N');
echo $dayofweek;
</pre>

==See also==
[[http://php.net/manual/en/class.datetime.php Php DateTime class]]
* [[Core APIs]]

[[Category:API]]

Time API

2020-05-21T11:52:32Z

Davidbalch: /* DST */

==Overview==

Internally Moodle always stores all times in unixtime format (number of seconds since epoch) which is independent of timezones.

The Time API is used to display proper date-time depending on user or site timezones.

==Functions==
There is a class in Moodle to handle most needs of working with times. There are 2 cases to consider when working with time:

System Time

This is when you are dealing with dates on the server e.g. executing scheduled tasks, performing background tasks - anything which does not depend on the timezone of any specific user.

User Time

This is when you are manipulating dates and times and you need to display them to the user in their current timezone (which may be different for each user).

The main API for time is in the class "core_date" which will give you php DateTimeZone objects for either user time or server time as needed. You can then use the php datetime classes to manipulate the time. When finished manipulating the time, get a timestamp with DateTime::getTimestamp().

Example: Get the current server time + 1 day.

<code>
$tomorrow = new DateTime("1 day", core_date::get_server_timezone_object());
</code>

Get a timestamp for storing in the database:
<code>
$tomorrowint = $tomorrow->getTimestamp();
</code>

Get a timestamp for 3pm tomorrow in the current users timezone.

<code>
$time = new DateTime("now", core_date::get_user_timezone_object());
$time->add(new DateInterval("P1D"));
$time->setTime(15, 0, 0);

$timestamp = $time->getTimestamp();
</code>

Remember! NEVER NEVER NEVER add or subtract timestamps for any reason - you will get it wrong (DST is a killer)!

Other functions related to time api can be found in lib/moodlelib.php.
# Time API's for current user
#* '''make_timestamp''' - Given date-time, it produces a GMT timestamp for current user.
#* '''userdate''' - Gets formatted string that represents a date in user time (note that the format required by this function is the [https://www.php.net/manual/en/function.strftime.php strftime()] format, not the more common format used by date())
#* '''usertime''' - Given a GMT timestamp (seconds since epoch), offsets it by the timezone. eg 3pm in India is 3pm GMT - 5.5 * 3600 seconds
#* '''usergetdate''' - Given a timestamp in GMT, returns an array that represents the date-time in user time
#* '''usergetmidnight''' - Given a date, return the GMT timestamp of the most recent midnight for the current user.
#* '''usertimezone''' - Returns current user's timezone

# System Time API
#* '''format_time''' - Format a date/time (seconds) as weeks, days, hours etc as needed
#* '''dst_offset_on''' - Calculates the Daylight Saving Offset for a given date/time (timestamp)
#* '''find_day_in_month''' - Calculates when the day appears in specific month
#* '''days_in_month''' - Calculate number of days in a given month
#* '''dayofweek''' - Calculate the position in the week of a specific calendar day

# Older legacy date/time functions. Do not use in new code.
#* '''usertime''' - Appends the users timezone offset to an integer timestamp
#* '''get_timezone_offset''' - Systems's timezone difference from GMT in seconds
#* '''get_user_timezone_offset''' - Returns user's timezone difference from GMT in hours
#* '''dst_changes_for_year''' - Calculates the required DST change and returns a Timestamp Array

==Glossary==
===Timezone===
Moodle supports following timezone formats:
# UTC (specifically UTC−11 to UTC+11)
# Time offsets from UTC (int +-(0-13) or float +-(0.5-12.5))
# World timezones (Australia/Perth)

===Location===
Timezone depends on [[:en:Location]] of the user and can be forced upon by administrator.
===DST===
DST is abbreviation of '''Daylight Saving Time''' (also known as "Day light saving" and "Summer Time"). Many countries, and sometimes just certain regions of countries, adopt daylight saving time during part of the year. Moodle automatically calculates DST for current user, depending on user location.

==Examples==
===Time API's for current user===
Prints a formatted date in user time
<pre>
// Get current day, month and year for current user.
$date = new DateTime("now", core_date::get_user_timezone_object());
$date->setTime(0, 0, 0);
// Print formatted date in user time.
echo userdate($date->getTimestamp(), "Current user time");
</pre>

===System Time API===
Find the day of the week for the first day in this month.

<pre>
$now = new DateTime("now", core_date::get_server_timezone_object());

$year = $now->format('Y');
$month = $now->format('m');

$now->setDate($year, $month, 1);
$dayofweek = $now->format('N');
echo $dayofweek;
</pre>

==See also==
[[http://php.net/manual/en/class.datetime.php Php DateTime class]]
* [[Core APIs]]

[[Category:API]]

Time API

2020-05-21T11:52:16Z

Davidbalch: /* DST */

==Overview==

Internally Moodle always stores all times in unixtime format (number of seconds since epoch) which is independent of timezones.

The Time API is used to display proper date-time depending on user or site timezones.

==Functions==
There is a class in Moodle to handle most needs of working with times. There are 2 cases to consider when working with time:

System Time

This is when you are dealing with dates on the server e.g. executing scheduled tasks, performing background tasks - anything which does not depend on the timezone of any specific user.

User Time

This is when you are manipulating dates and times and you need to display them to the user in their current timezone (which may be different for each user).

The main API for time is in the class "core_date" which will give you php DateTimeZone objects for either user time or server time as needed. You can then use the php datetime classes to manipulate the time. When finished manipulating the time, get a timestamp with DateTime::getTimestamp().

Example: Get the current server time + 1 day.

<code>
$tomorrow = new DateTime("1 day", core_date::get_server_timezone_object());
</code>

Get a timestamp for storing in the database:
<code>
$tomorrowint = $tomorrow->getTimestamp();
</code>

Get a timestamp for 3pm tomorrow in the current users timezone.

<code>
$time = new DateTime("now", core_date::get_user_timezone_object());
$time->add(new DateInterval("P1D"));
$time->setTime(15, 0, 0);

$timestamp = $time->getTimestamp();
</code>

Remember! NEVER NEVER NEVER add or subtract timestamps for any reason - you will get it wrong (DST is a killer)!

Other functions related to time api can be found in lib/moodlelib.php.
# Time API's for current user
#* '''make_timestamp''' - Given date-time, it produces a GMT timestamp for current user.
#* '''userdate''' - Gets formatted string that represents a date in user time (note that the format required by this function is the [https://www.php.net/manual/en/function.strftime.php strftime()] format, not the more common format used by date())
#* '''usertime''' - Given a GMT timestamp (seconds since epoch), offsets it by the timezone. eg 3pm in India is 3pm GMT - 5.5 * 3600 seconds
#* '''usergetdate''' - Given a timestamp in GMT, returns an array that represents the date-time in user time
#* '''usergetmidnight''' - Given a date, return the GMT timestamp of the most recent midnight for the current user.
#* '''usertimezone''' - Returns current user's timezone

# System Time API
#* '''format_time''' - Format a date/time (seconds) as weeks, days, hours etc as needed
#* '''dst_offset_on''' - Calculates the Daylight Saving Offset for a given date/time (timestamp)
#* '''find_day_in_month''' - Calculates when the day appears in specific month
#* '''days_in_month''' - Calculate number of days in a given month
#* '''dayofweek''' - Calculate the position in the week of a specific calendar day

# Older legacy date/time functions. Do not use in new code.
#* '''usertime''' - Appends the users timezone offset to an integer timestamp
#* '''get_timezone_offset''' - Systems's timezone difference from GMT in seconds
#* '''get_user_timezone_offset''' - Returns user's timezone difference from GMT in hours
#* '''dst_changes_for_year''' - Calculates the required DST change and returns a Timestamp Array

==Glossary==
===Timezone===
Moodle supports following timezone formats:
# UTC (specifically UTC−11 to UTC+11)
# Time offsets from UTC (int +-(0-13) or float +-(0.5-12.5))
# World timezones (Australia/Perth)

===Location===
Timezone depends on [[:en:Location]] of the user and can be forced upon by administrator.
===DST===
DST is abbreviation of '''Daylight Saving Time''' (also known as '''Day light saving''' and "Summer Time"). Many countries, and sometimes just certain regions of countries, adopt daylight saving time during part of the year. Moodle automatically calculates DST for current user, depending on user location.

==Examples==
===Time API's for current user===
Prints a formatted date in user time
<pre>
// Get current day, month and year for current user.
$date = new DateTime("now", core_date::get_user_timezone_object());
$date->setTime(0, 0, 0);
// Print formatted date in user time.
echo userdate($date->getTimestamp(), "Current user time");
</pre>

===System Time API===
Find the day of the week for the first day in this month.

<pre>
$now = new DateTime("now", core_date::get_server_timezone_object());

$year = $now->format('Y');
$month = $now->format('m');

$now->setDate($year, $month, 1);
$dayofweek = $now->format('N');
echo $dayofweek;
</pre>

==See also==
[[http://php.net/manual/en/class.datetime.php Php DateTime class]]
* [[Core APIs]]

[[Category:API]]

PHPUnit

2019-11-06T09:26:47Z

Davidbalch:

{{Moodle 2.3}}

=What is PHPUnit=
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.

Read the excellent guide at
* [https://phpunit.de/documentation.html PHPUnit Manual]

=Installation of PHPUnit via Composer=

* Install Composer

Instructions for installing composer on all platforms are here: https://getcomposer.org/download/

Install the composer.phar file to your moodle folder.

* Execute Composer installer

cd /your/moodle/dirroot

php composer.phar install

(If that gives you connection problems try...)

php composer.phar install --prefer-source

Troubleshooting:
* On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
* You may be prompted for github credentials when installing composer dependencies.
** This is used to generate an personal access token to avoid being rate limited by github.
** If you have Two Factor Authentication enabled on your github account, or do not wish to supply your own credentials you will need to generate a token manually:
*** Visit https://github.com/settings/applications and request personal access token
*** Copy this token and add it to your [https://gist.github.com/andrewnicols/c5377ed25a9df1006ce1 ~/.composer/config.json]
** ( See [https://github.com/composer/composer/issues/2280 composer issue #2280] for further details of this bug.)

Detailed instructions:
* [http://getcomposer.org/doc/00-intro.md Composer documentation]

Detailed instructions:
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in OS X]]

== Uninstalling previous PEAR based version ==

Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:

$ pear uninstall phpunit/DbUnit
$ pear uninstall phpunit/PHPUnit

=Initialisation of test environment=

Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').

$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/home/example/phpu_moodledata';

Some PHPUnit tests require a live internet connection. If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.

// Normal proxy settings
$CFG->proxyhost = 'wwwcache.example.org';
$CFG->proxyport = 80;
$CFG->proxytype = 'HTTP';
$CFG->proxybypass = 'localhost, 127.0.0.1, .example.org';
// Omit the next lines if your proxy doesn't need a username/password:
$CFG->proxyuser = 'systemusername';
$CFG->proxypassword = 'systempassword';

From Moodle 2.8.5 onwards, you can also provide specific database settings for unit testing (if these are not provided, the standard database settings will be used):

<pre>$CFG->phpunit_dbtype = 'pgsql'; // 'pgsql', 'mariadb', 'mysqli', 'mssql', 'sqlsrv' or 'oci'
$CFG->phpunit_dblibrary = 'native'; // 'native' only at the moment
$CFG->phpunit_dbhost = '127.0.0.1'; // eg 'localhost' or 'db.isp.com' or IP
$CFG->phpunit_dbname = 'mytestdb'; // database name, eg moodle
$CFG->phpunit_dbuser = 'postgres'; // your database username
$CFG->phpunit_dbpass = 'some_password'; // your database password</pre>

Then you need to initialise the test environment using following command.

cd /home/example/moodle
php admin/tool/phpunit/cli/init.php

This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:

'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly. Also, ensure en_AU locale is installed on your server.

== LDAP ==
If you want to run LDAP unit tests you must have a working, configured LDAP environment on your test server. There must be a basic LDAP tree structure in place or tests will fail with "Search: No such object". Build an LDAP tree structure in a new shell prompt:

<pre>
$ ldapadd -H ldap://127.0.0.1 -D "cn=admin,dc=yourcomputer,dc=local" -W
dn:dc=yourcomputer,dc=local
objectClass:dcObject
objectClass:organizationalUnit
dc:yourcomputer
ou:YOURCOMPUTER
</pre>

In config.php tell Moodle where to look for your test LDAP environment:

<pre>
// Constants for auth/ldap tests.
define('TEST_AUTH_LDAP_HOST_URL', 'ldap://127.0.0.1');
define('TEST_AUTH_LDAP_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_AUTH_LDAP_BIND_PW', '*');
define('TEST_AUTH_LDAP_DOMAIN', 'dc=yourcomputer,dc=local');

// Constants for enrol/ldap tests.
define('TEST_ENROL_LDAP_HOST_URL', 'ldap://127.0.0.1');
define('TEST_ENROL_LDAP_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_ENROL_LDAP_BIND_PW', '*');
define('TEST_ENROL_LDAP_DOMAIN', 'dc=yourcomputer,dc=local');

// Constants for lib/ldap tests.
define('TEST_LDAPLIB_HOST_URL', 'ldap://127.0.0.1');
define('TEST_LDAPLIB_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_LDAPLIB_BIND_PW', '*');
define('TEST_LDAPLIB_DOMAIN', 'dc=yourcomputer,dc=local');
</pre>

=Test execution=

To execute all test suites from main configuration file execute the <code>vendor/bin/phpunit</code> script from your <code>$CFG->dirroot</code> directory.

cd /home/example/moodle
vendor/bin/phpunit

The rest of examples uses <code>phpunit</code>, please substitute it with <code>vendor/bin/phpunit</code> or create a shortcut in your dirroot.

In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <code>phpunit.xml</code> from your <code>$CFG->dirroot</code>.

There is an alternative script for running of tests via web interface: <code>admin/tool/phpunit/webrunner.php</code>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.

===How to run only some tests===

==== Running a single test quickly ====

The fastest way to run a single test is:

<code php>
vendor/bin/phpunit my/tests/filename.php
</code>
so, run this command in the CLI to see a real test in action:
<code php>
vendor/bin/phpunit cohort/tests/cohortlib_test.php
</code>

You can also run a single test method inside a class:
<code php>
vendor/bin/phpunit --filter test_function_name path/to/file.php
</code>

Note: You should be careful because it may be possible to run tests this way which are not included in the normal run if, for example, the file is not placed in the correct location. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.

Filters can also be applied to capture a group of similar tests across all testsuites:
<code php>
vendor/bin/phpunit --filter test_flag_user
</code>

It is also possible to run all tests in a component by using the testsuite option:
<code bash>
vendor/bin/phpunit --testsuite core_privacy_testsuite
vendor/bin/phpunit --testsuite core_privacy_testsuite --filter test_component_is_compliant
</code>

==== Using the @group annotation ====

If you add annotations like

<code php>
/**
* Unit tests for {@link stack_cas_keyval}.
* @group qtype_stack
*/
class qtype_stack_cas_keyval_exception_testcase extends basic_testcase {
</code>

to all the classes in your plugin, then you can run just the tests for your plugin by doing

phpunit --group qtype_stack

Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.

==== Using multiple phpunit.xml files ====

It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with

vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml

Also, for commodity, you can use this command:

php admin/tool/phpunit/cli/util.php --buildcomponentconfigs

It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like

vendor/bin/phpunit -c mod/forum[/phpunit.xml] // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
vendor/bin/phpunit -c question
vendor/bin/phpunit -c question/type/calculated
vendor/bin/phpunit -c backup
vendor/bin/phpunit -c lib/dml
...

or, also

cd directory/with/phpunit.xml
phpunit

=External test resources=
{{Moodle 2.6}}
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:

# clone https://github.com/moodlehq/moodle-exttests to web directory
# add to your config.php or modify phpunit.xml file <code php>define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</code>

=Writing new tests=
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* see [[Writing PHPUnit tests]]

=Conversion of existing SimpleTests=
* see [[SimpleTest conversion]]

=PHPUnit support in IDEs=

* [[Setting up Eclipse]]
* [[Setting up Netbeans]]
* [[Setting up PhpStorm]]

=Common Unit Test Problems=
[[Common unit test problems]]

=Performance=

A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:

* Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
* Apply developer-only performance settings to your database: [[Postgres Tuning For Developers]]

=Command line tips=

* Run all tests for a plugin (mod_mymodule in this example): vendor/bin/phpunit --testsuite=mod_mymodule_testsuite
* Run only named test: vendor/bin/phpunit --filter=test_my_test_function_name
* Display each test name before running it (useful e.g. if it crashes before the end and you want to know which test it was running at that point) vendor/bin/phpunit --debug (you will probably want to redirect this to a file as it gets very long).

[[Category:Unit testing]]

Form API

2019-08-23T10:47:49Z

Davidbalch: /* Highlights */

==Overview==
Web Forms in moodle are created using forms API. Form API supports all html elements (checkbox, radio, textbox etc), with improved accessibility and security.
==Highlights==
# Tested and optimised for use on major screen-readers Dragon and JAWS.
# Tableless layout.
# Process form data securely, with required_param, optional_param and session key.
# Supports client-side validation
# Facility to add Moodle help buttons to forms.
# Support for file repository using [[File_API]]
# Support for many custom moodle specific and non-specific form elements.
# Addition for [https://docs.moodle.org/dev/lib/formslib.php_repeat_elements repeated elements].
# Addition for form elements in advance group

==Usage==
For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.
<code php>
//moodleform is defined in formslib.php
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {
//Add elements to form
public function definition() {
global $CFG;

$mform = $this->_form; // Don't forget the underscore!

$mform->addElement('text', 'email', get_string('email')); // Add elements to your form
$mform->setType('email', PARAM_NOTAGS); //Set type of element
$mform->setDefault('email', 'Please enter email'); //Default value
...
}
//Custom validation should be added here
function validation($data, $files) {
return array();
}
}
</code>
Then instantiate form (in this case simplehtml_form) on your page.
<code php>
//include simplehtml_form.php
require_once('PATH_TO/simplehtml_form.php');

//Instantiate simplehtml_form
$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);
//displays the form
$mform->display();
}
</code>

If you wish to use the form within a block then you should consider using the render method, as demonstrated below:

Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you've included the file which contains the class for your Moodle form.

<code php>
class block_yourblock extends block_base{
public function init(){
$this->title = 'Your Block';
}
public function get_content(){

$this->content = new stdClass();
$this->content->text = '';

$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);

//displays the form
$this->content->text = $mform->render();
}

return $this->content;

}
}
</code>

==Form elements==
===Basic form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#button button]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#checkbox checkbox]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#radio radio]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#select select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#multi-select multi-select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#password password]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#hidden hidden]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#html html] - div element
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#static static] - Display a static text.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#text text]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#textarea textarea]

===Custom form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete Autocomplete] - A select box that allows you to start typing to narrow the list of options, or search for results.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#advcheckbox advcheckbox] - Advance checkbox
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#float float]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#passwordunmask passwordunmask] - A password element with option to show the password in plaintext.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#recaptcha recaptcha]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectyesno selectyesno]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectwithlink selectwithlink]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_selector date_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_time_selector date_time_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#duration duration]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#editor editor]
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filepicker filepicker] - upload single file
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filemanager filemanager] - upload multiple files
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#tags tags]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#addGroup addGroup]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modgrade modgrade]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modvisible modvisible]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#choosecoursefile choosecoursefile]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#grading grading]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#questioncategory questioncategory]

==Commonly used functions==

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges'). Note the '''$this''' not '''$mform'''

<code php>
$this->add_action_buttons();
</code>

====[[lib/formslib.php_Form_Definition#setDefault_2|setDefault()]]====
To set the default value for an element.

====[[lib/formslib.php_Form_Definition#disabledIf|disabledIf()]]====
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

====[[lib/formslib.php_Form_Definition#hideIf|hideif()]]====
For any element or groups of element in a form you can conditionally hide the group or individual element depending on conditions.
Same syntax as disabledIf. Can do a simple search and replace on disabledIf. Added in Moodle 3.4.

====[[lib/formslib.php_Form_Definition#addRule|addRule()]]====
Add rule for server/client side validation. Like text field is required element and is of type email.

====[[lib/formslib.php_Form_Definition#setHelpButton|setHelpButton()]]====
Sets pop-up help button to a form element.

====[[lib/formslib.php_Form_Definition#addHelpButton|addHelpButton()]]====
Adds pop-up help button to a form element

====[[lib/formslib.php_Form_Definition#setType|setType()]]====
PARAM_* types are used to specify how a submitted variable should be cleaned.

====[[lib/formslib.php_Form_Definition#disable_form_change_checker|disable_form_change_checker()]]====
By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call <tt>$mform->disable_form_change_checker()</tt>.

==FAQ==
[https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements How to group elements]
==See also==

* [[Core_APIs]]
* [[lib/formslib.php_Usage]]
* [[lib/formslib.php_Form_Definition]]
* [[Designing usable forms]]
* [[Fragment]]
* [[MForm_Modal]]

[[Category:API]]

Javascript Modules

2017-08-01T16:12:24Z

Davidbalch: /* Including an external javascript/jquery library */ Tweak example numbering.

{{Moodle 2.9}}

= Javascript Modules =

== What is a Javascript module and why do I care? ==

A Javascript module is nothing more than a collection of Javascript code that can be used (reliably) from other pieces of Javascript.

== Why should I package my code as a module? ==

By packaging your code as a module you break your code up into smaller reusable pieces. This is good because:

a) Each smaller piece is simpler to understand / debug

b) Each smaller piece is simpler to test

c) You can re-use common code instead of duplicating it

= How do I write a Javascript module in Moodle? =

Since version 2.9, Moodle supports Javascript modules written using the Asynchronous Module Definition ([https://github.com/amdjs/amdjs-api/wiki/AMD AMD]) API. This is a standard API for creating Javascript modules and you will find many useful third party libraries that are already using this format.

To edit or create an AMD module in Moodle you need to do a couple of things.

== Install grunt ==

The AMD modules in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[http://gruntjs.com/ grunt]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment.

This means you first have to '''install nodejs''' - and its package manager [https://www.npmjs.com/ npm]. The details of how to install those packages will vary by operating system, but on Linux it's probably similar to "sudo apt-get install nodejs npm". There are downloadable packages for other operating systems here: http://nodejs.org/download/. Moodle currently requires node "v4" and does not work with the latest node "v6".

Once this is done, you can '''run the command''':

npm install
npm install -g grunt-cli

from the top of the Moodle directory to install all of the required tools. (You may need extra permissions to use the -g option.)

== Development mode ==

To avoid having to constantly run grunt, make sure you set the following in your config.php

<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Moodle will now run your module from the amd/src module. Don't forget to switch this off and run 'grunt' before deploying the new version!

In this mode - if you get a strange message in your javascript console like "No define call for core/first" it means you have a syntax error in the javascript you are developing.

== Running grunt ==

You can run grunt in your plugin's 'amd' directory and it will only operate on your modules. If you're having problems or just want to check your work it is worth running for the 'lint' feature. This can find basic problems. This sub-directory support wont work on Windows unfortunately but there is an alternative: Run grunt from the top directory with the --root=path/to/dir to limit execution to a sub-directory.

See [[Grunt#Running_grunt]] for more details of specific grunt commands which can be used.

If you get the error message

/usr/bin/env: node: No such file or directory

Then see the thread https://github.com/nodejs/node-v0.x-archive/issues/3911

On Ubuntu 14.04 this fixed it for me:

sudo ln -fs /usr/bin/nodejs /usr/local/bin/node

== Minimum (getting started) module for plugins ==

This shows the absolute minimum module you need to get started adding modules to your plugins. It's actually quite simple...

<code javascript>
// Put this file in path/to/plugin/amd/src
// You can call it anything you like

define(['jquery'], function($) {

return {
init: function() {

// Put whatever you like here. $ is available
// to you as normal.
$(".someclass").change(function() {
alert("It changed!!");
});
}
};
});
</code>

The idea here is that we will run the 'init' function from our (PHP) code to set things up. This is called from PHP like this...

<code php>
$PAGE->requires->js_call_amd('frankenstyle_path/your_js_filename', 'init');
</code>

Don't forget to supply the complete 'frankenstyle' path. The .js is not needed.

js_call_amd takes a third parameter which is an ''array'' of parameters. These will translate to individual parameters in the 'init' function call. For example...

<code php>
$PAGE->requires->js_call_amd('block_iomad_company_admin/department_select', 'init', array($first, $last));
</code>

...calls

<code javascript>
return {
init: function(first, last) {
}
</code>

A more comprehensive explanation follows...

== "Hello World" I am a Javascript Module ==
Lets now create a simple Javascript module so we can see how to lay things out.

Each Javascript module is contained in a single source file in the <componentdir>/amd/src folder. The final name of the module is taken from the file name and the component name. E.g. block_overview/amd/src/helloworld.js would be a module named "block_overview/helloworld". the name of the module is important when you want to call it from somewhere else in the code.

After running grunt - the minified Javascript files are stored in the <componentdir>/amd/build folder. The javascript files are renamed to show that they are minified (helloworld.js becomes helloworld.min.js).

Don't forget to add the built files (the ones in amd/build) to your git commits, or in production no-one will see your changes.

Lets create a simple module now:

blocks/overview/amd/src/helloworld.js
<code javascript>
// Standard license block omitted.
/*
* @package block_overview
* @copyright 2015 Someone cool
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

/**
* @module block_overview/helloworld
*/
define(['jquery'], function($) {

/**
* Give me blue.
* @access private
* @return {string}
*/
var makeItBlue = function() {
// We can use our jquery dependency here.
return $('.blue').show();
};

/**
* @constructor
* @alias module:block_overview/helloworld
*/
var greeting = function() {
/** @access private */
var privateThoughts = 'I like the colour blue';

/** @access public */
this.publicThoughts = 'I like the colour orange';

};

/**
* A formal greeting.
* @access public
* @return {string}
*/
greeting.prototype.formal = function() {
return 'How do you do?';
};

/**
* An informal greeting.
* @access public
* @return {string}
*/
greeting.prototype.informal = function() {
return 'Wassup!';
};
return greeting;
});
</code>

The most interesting line above is:
<code>
define(['jquery'], function($) {
</code>

All AMD modules must call "define()" as the first and only global scoped piece of code. This ensures the javascript code contains no global variables and will not conflict with any other loaded module. The name of the module does not need to be specified because it is determined from the filename and component (but it can be listed in a comment for JSDoc as shown here).

The first argument to "define" is the list of dependencies for the module. This argument must be passed as an array, even if there is only one. In this example "jquery" is a dependency. "jquery" is shipped as a core module is available to all AMD modules.

The second argument to "define" is the function that defines the module. This function will receive as arguments, each of the requested dependencies in the same order they were requested. In this example we receive JQuery as an argument and we name the variable "$" (it's a JQuery thing). We can then access JQuery normally through the $ variable which is in scope for any code in our module.

The rest of the code in this example is a standard way to define a Javascript module with public/private variables and methods. There are many ways to do this, this is only one.

It is important that we are returning 'greeting'. If there is no return then your module will be declared as undefined.

== Loading modules dynamically ==
What do you do if you don't know in advance which modules will be required? Stuffing all possible required modules in the define call is one solution, but it's ugly and it only works for code that is in an AMD module (what about inline code in the page?). AMD lets you load a dependency any time you like.
<code javascript>

// Load a new dependency.
require(['mod_wiki/timer'], function(timer) {
// timer is available to do my bidding.
});
</code>

== Including an external javascript/jquery library ==
If you want to include a javascript / jquery library downloaded from the internet you can do so as follows:

'''Warning: if the library you download, supports AMD but is already "named" you will not be able to include it directly'''
e.g.
<code javascript>
define("typeahead.js", *[ "jquery" ], function(a0) {
return factory(a0);
});
</code>
will not work, as moodle injects it's own define name when loading the library.

If the library is in AMD format and has a define:
e.g. i want to include the jquery final countdown timer on my page ( hilios.github.io/jQuery.countdown/ )
* download the module in both normal and minified versions
* place the modules in your moodle install e.g. your custom theme dir, or plugin dir
* /theme/mytheme/amd/src/jquery.countdown.js

you can now include the module and initialise it (there are multiple ways to do this)
php:

1. Create your own AMD module and initialise it:

In your PHP file:
<code php>
$this->page->requires->js_call_amd('theme_mytheme/countdowntimer', 'initialise', $params);
</code>

Javascript module:
<code javascript>
// /theme/mytheme/amd/src/countdowntimer.js
define(['jquery', 'theme_mytheme/jquery.countdown'], function($, c) {
return {
initialise: function ($params) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
}
};
});
</code>

2. Put the javascript into a mustache template:
<code javascript>
// /theme/mytheme/templates/countdowntimer.mustache

{{#js}}
require(['jquery', 'theme_mytheme/jquery.countdown'], function($) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
{{/js}}
</code>

3. Call the javascript directly from php (although who would want to put javascript into php? ergh):
<code php>
$PAGE->requires->js_amd_inline('
require(['theme_mytheme/jquery.countdown'], function(min) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
');
</code>

== Embedding AMD code in a page ==
So you have created lots of cool Javascript modules. Great. How do we actually call them? Any javascript code that calls an AMD module must execute AFTER the requirejs module loader has finished loading. We have provided a function "js_call_amd" that will call a single function from an AMD module with parameters.

<code php>
$PAGE->requires->js_call_amd($modulename, $functionname, $params);
</code>

that will "do the right thing" with your block of AMD code and execute it at the end of the page, after our AMD module loader has loaded.
Notes:
* the $modulename is the 'componentname/modulename' discussed above
* the $functionname is the name of a public function exposed by the amd module.
* the $params is an array of params passed as arguments to the function. These should be simple types that can be handled by json_encode (no recursive arrays, or complex classes please).
* if the size of the params array is too large (> 1Kb), this will produce a developer warning. Do not attempt to pass large amounts of data through this function, it will pollute the page size. A preferred approach is to pass css selectors for DOM elements that contain data-attributes for any required data, or fetch data via ajax in the background.

AMD / JS code can also be embedded on a page via mustache templates
see here: https://docs.moodle.org/dev/Templates#What_if_a_template_contains_javascript.3F

== But I have a mega JS file I don't want loaded on every page? ==
Loading all JS files at once and stuffing them in the browser cache is the right choice for MOST js files, there are probably some exceptions. For these files, you can rename the javascript file to end with the suffix "-lazy.js" which indicates that the module will not be loaded by default, it will be requested the first time it is used. There is no difference in usage for lazy loaded modules, the require() call looks exactly the same, it's just that the module name will also have the "-lazy" suffix.

[[Category:AJAX]]
[[Category:Javascript]]

ctags

2017-05-12T10:29:28Z

Davidbalch: /* Moodle 1.9.6 and newer */ Update contents of tags.txt

== Moodle 1.9.6 and newer ==
As of Moodle 1.9.6 the tags file is no longer included in the Moodle distribution. Instead a file tags.txt is included providing instructions on creating the tag file yourself. The text of this file is as follows:

<pre>
Generating a tags file
======================

If you need a tags file so that you can jump around Moodle code
easily in your editor (eg vim or emacs), you can generate one:

Exuberant ctags (default on Linux, can be compiled on other platforms):
----------------------------------------------------------------------

ctags -R --languages=php --php-kinds=f \
--regex-PHP='/abstract +class +([^ ]*)/\1/c/' \
--regex-PHP='/interface +([^ ]*)/\1/c/' \
--regex-PHP='/(public |static |abstract |protected |private )+ *function +([^ (]*)/\2/f/'

BSD ctags (Default on Mac OS X):
-------------------------------

(TODO)
</pre>

== Using tags with Vim ==

In order to use the tags file with the Vim editor (on a Unix style system), you should first add the following line to the file '''.vimrc''' in your home directory:

set tags=tags;/

If .vimrc does not exist you should create it. This directive will force Vim to search for the tags file in the directory tree in which you are working (it searches up from where you are) so it will work for multiple versions of the code automatically.

=== How to jump to a tag with Vim ===

There are a number of things you can do:

* Place the cursor over the tag (e.g., function name) and press '''CTRL+]'''.
* Type the command ''':tag <tagname>'''
* To open in a new editor window type the command ''':stag <tagname>'''
* To return to your previous location type '''CTRL+t'''

== Using tags with Emacs ==
To create the TAGS file add a -e to the command of tags.txt, like this:
<pre>
ctags -e -R --languages=php --exclude="CVS" --php-kinds=f \
--regex-PHP='/abstract class ([^ ]*)/\1/c/' \
--regex-PHP='/interface ([^ ]*)/\1/c/' \
--regex-PHP='/(public |static |abstract |protected |private )+function ([^ (]*)/\2/f/'
</pre>

For instructions about how to use it look to the emacs wiki page [http://www.emacswiki.org/emacs/EmacsTags EmacsTags]

==See also==

* [http://www.vim.org/tips/tip.php?tip_id=94 Vim tags usage tip]
* [http://vimdoc.sourceforge.net/htmldoc/usr_29.html#29.1 Vim documentation: Using tags]
* [http://vimdoc.sourceforge.net/htmldoc/tagsrch.html Vim documentation: Tags and special searches]

[[Category:Developer tools]]

Plugin types

2016-07-20T11:03:37Z

Davidbalch: Remove duplicate "Antivirus plugins" row.

{{Plugins development}}

The M in Moodle stands for modular. The easiest and most maintainable way to add new functionality to Moodle is by writing one of these types of plugin.
If none of the standardized types fits your needs, you can use the "local" type.

== List of Moodle plugin types ==

{| class="nicetable"
|-
! Plugin type
! Component name ([[Frankenstyle]])
! Moodle path
! Description
! Moodle versions
|-
| [[Activity modules]]
| mod
| /mod
| Activity modules are essential types of plugins in Moodle as they provide activities in courses. For example: Forum, Quiz and Assignment.
| 1.0+
|-
| [[Antivirus plugins]]
| antivirus
| /lib/antivirus
| Antivirus scanner plugins provide functionality for virus scanning user uploaded files using third-party virus scanning tools in Moodle. For example: ClamAV.
| 3.1+
|-
| [[Assign_submission_plugins|Assignment submission plugins]]
| assignsubmission
| /mod/assign/submission
| Different forms of assignment submissions
| 2.3+
|-
| [[Assign_feedback_plugins|Assignment feedback plugins]]
| assignfeedback
| /mod/assign/feedback
| Different forms of assignment feedbacks
| 2.3+
|-
| [[Book tools]]
| booktool
| /mod/book/tool
| Small information-displays or tools that can be moved around pages
| 2.1+
|-
| [[Database fields]]
| datafield
| /mod/data/field
| Different types of data that may be added to the Database activity module
| 1.6+
|-
| [[Database presets]]
| datapreset
| /mod/data/preset
| Pre-defined templates for the Database activity module
| 1.6+
|-
| [[External tool source|LTI sources]]
| ltisource
| /mod/lti/source
| LTI providers can be added to external tools easily through the external tools interface see [https://docs.moodle.org/en/External_tool Documentation on External Tools]. This type of plugin is specific to LTI providers that need a plugin that can register custom handlers to process LTI messages
| 2.7+
|-
| [[LTI services]]
| ltiservice
| /mod/lti/service
| Allows the implementation of LTI services as described by the IMS LTI specification
| 2.8+
|-
| [[Quiz reports]]
| quiz
| /mod/quiz/report
| Display and analyse the results of quizzes, or just plug miscellaneous behaviour into the quiz module
| 1.1+
|-
| [[Quiz access rules]]
| quizaccess
| /mod/quiz/accessrule
| Add conditions to when or where quizzes can be attempted, for example only from some IP addresses, or student must enter a password first
| 2.2+
|-
| [[SCORM reports]]
| scormreport
| /mod/scorm/report
| Analysis of SCORM attempts
| 2.2+
|-
| [[Workshop grading strategies]]
| workshopform
| /mod/workshop/form
| Define the type of the grading form and implement the calculation of the grade for submission in the [[Workshop]] module
| 2.0+
|-
| [[Workshop allocation methods]]
| workshopallocation
| /mod/workshop/allocation
| Define ways how submissions are assigned for assessment in the [[Workshop]] module
| 2.0+
|-
| [[Workshop evaluation methods]]
| workshopeval
| /mod/workshop/eval
| Implement the calculation of the grade for assessment (grading grade) in the [[Workshop]] module
| 2.0+
|-
| [[Blocks]]
| block
| /blocks
| Small information-displays or tools that can be moved around pages
| 2.0+
|-
| [[Question types]]
| qtype
| /question/type
| Different types of question (e.g. multiple-choice, drag-and-drop) that can be used in quizzes and other activities
| 1.6+
|-
| [[Question behaviours]]
| qbehaviour
| /question/behaviour
| Control how student interact with questions during an attempt
| 2.1+
|-
| [[Question formats|Question import/export formats]]
| qformat
| /question/format
| Import and export question definitions to/from the question bank
| 1.6+
|-
| [[Filters|Text filters]]
| filter
| /filter
| Automatically convert, highlight, and transmogrify text posted into Moodle.
| 1.4+
|-
| [[Editors]]
| editor
| /lib/editor
| Alternative text editors for editing content
| 2.0+
|-
| [[Atto|Atto editor plugins]]
| atto
| /lib/editor/atto/plugins
| Extra functionality for the Atto text editor
| 2.7+
|-
| [[TinyMCE editor plugins]]
| tinymce
| /lib/editor/tinymce/plugins
| Extra functionality for the TinyMCE text editor.
| 2.4+
|-
| [[Enrolment plugins]]
| enrol
| /enrol
| Ways to control who is enrolled in courses
| 2.0+
|-
| [[Authentication plugins]]
| auth
| /auth
| Allows connection to external sources of authentication
| 2.0+
|-
| [[Admin tools]]
| tool
| /admin/tool
| Provides utility scripts useful for various site administration and maintenance tasks
| 2.2+
|-
| [[Log stores]]
| logstore
| /admin/tool/log/store
| Event logs storage back-ends
| 2.7+
|-
| [[Availability conditions]]
| availability
| /availability/condition
| Conditions to restrict user access to activities and sections.
| 2.7+
|-
| [[Calendar types]]
| calendartype
| /calendar/type
| Defines how dates are displayed throughout Moodle
| 2.6+
|-
| [[Messaging consumers]]
| message
| /message/output
| Represent various targets where messages and notifications can be sent to (email, sms, jabber, ...)
| 2.0+
|-
| [[Course formats]]
| format
| /course/format
| Different ways of laying out the activities and blocks in a course
| 1.3+
|-
| [[Data formats]]
| dataformat
| /dataformat
| Formats for data exporting and downloading
| 3.1+
|-
| [[User profile fields]]
| profilefield
| /user/profile/field
| Add new types of data to user profiles
| 1.9+
|-
| [[Reports]]
| report
| /report
| Provides useful views of data in a Moodle site for admins and teachers
| 2.2+
|-
| [[Course reports]]
| coursereport
| /course/report
| Reports of activity within the course
| Up to 2.1 (for 2.2+ see [[Reports]])
|-
| [[Gradebook export]]
| gradeexport
| /grade/export
| Export grades in various formats
| 1.9+
|-
| [[Gradebook import]]
| gradeimport
| /grade/import
| Import grades in various formats
| 1.9+
|-
| [[Gradebook reports]]
| gradereport
| /grade/report
| Display/edit grades in various layouts and reports
| 1.9+
|-
| [[Grading methods|Advanced grading methods]]
| gradingform
| /grade/grading/form
| Interfaces for actually performing grading in activity modules (eg Rubrics)
| 2.2+
|-
| [[MNet services]]
| mnetservice
| /mnet/service
| Allows to implement remote services for the [[MNet]] environment (deprecated, use web services instead)
| 2.0+
|-
| [[Webservice protocols]]
| webservice
| /webservice
| Define new protocols for web service communication (such as SOAP, XML-RPC, JSON, REST ...)
| 2.0+
|-
| [[Repository plugins]]
| repository
| /repository
| Connect to external sources of files to use in Moodle
| 2.0+
|-
| [[Portfolio plugins]]
| portfolio
| /portfolio
| Connect external portfolio services as destinations for users to store Moodle content
| 1.9+
|-
| [[Search engines]]
| search
| /search/engine
| Search engine backends to index Moodle's contents.
| 3.1+
|-
| [[Plagiarism plugins]]
| plagiarism
| /plagiarism
| Define external services to process submitted files and content
| 2.0+
|-
| [[Cache store]]
| cachestore
| /cache/stores
| Cache storage back-ends.
| 2.4+
|-
| [[Cache locks]]
| cachelock
| /cache/locks
| Cache lock implementations.
| 2.4+
|-
| [[Themes]]
| theme
| /theme
| Change the look of Moodle by changing the the HTML and the CSS.
| 2.0+
|-
| [[Local plugins]]
| local
| /local
| Generic plugins for local customisations
| 2.0+
|-
| [[Assignment types|Legacy assignment types]]
| assignment
| /mod/assignment/type
| Different forms of assignments to be graded by teachers
| 1.x - 2.2
|-
| [[Admin reports|Legacy admin reports]]
| report
| /admin/report
| Provides useful views of data in a Moodle site, for admins only.
| Up to 2.1 (for 2.2+ see [[Reports]])
|}

== Obtaining the list of plugin types known to your Moodle ==

To get the most exact list of types in your version of Moodle, use the following script. Put it to a file in the root directory of your Moodle installation and execute it via command line.

<code php>
<?php
define('CLI_SCRIPT', true);
require('config.php');

$pluginman = core_plugin_manager::instance();

foreach ($pluginman->get_plugin_types() as $type => $dir) {
$dir = substr($dir, strlen($CFG->dirroot));
printf("%-20s %-50s %s".PHP_EOL, $type, $pluginman->plugintype_name_plural($type), $dir);
}
</code>

==Things you can find in all plugins==

Although there are many different types of plugin, there are some things that work the same way in all plugin types, and we have [[Things that work the same in all plugin types|a page that describes them]].

Additionally you probably want to look at the page [[Plugin files]].

== Naming conventions ==

Warning if you have to choose a plugin (directory) name. The name is validated by the method <tt>lib/classes/component.php::is_valid_plugin_name()</tt> with a regexp: <tt>/^[a-z](?:[a-z0-9_](?!__))*[a-z0-9]+$/</tt>. In particular, the minus (-) character is not considered as valid, and the plugin will be silently ignored if the name is not valid.

There is an exception for [[Activity modules|activity modules]] that can not have the underscore in their name for legacy reasons.

== See also ==

* [[Guidelines_for_contributed_code|Guidelines for contributing code]]
* [[Core APIs]]
* [[Frankenstyle]]
* [http://moodle.org/plugins Moodle Plugins directory]
* [[Tutorial]] to help you learn how to write plugins for Moodle from start to finish, while showing you how to navigate the most important developer documentation along the way.

[[Category:Coding guidelines|Plugins]]
[[Category:Plugins]]

Navigation API

2016-06-16T08:54:17Z

Davidbalch: /* Code extension */ I wasted hours trying to get callbacks in lib.php working before realising that I needed to use settings.php. Hopfully this will help save others the same experience.

==Overview==
The Navigation API allows for the manipulation of the navigation system used in Moodle.

==What the navigation is==
It's very important to understand what the navigation is exactly within Moodle. One of the goals for Moodle 2.0 was to standardise navigation throughout Moodle and try to bring order to the structure of a Moodle site. Navigation is available through the page object '''$PAGE''', against which you set the heading for the page, the title, any JavaScript requirements, etc. The navigation structure uses the information $PAGE contains to generate a navigation structure for the site. The navigation or settings [[blocks]] are interpretations of the navigation structure Moodle creates.

This navigation structure is available through three variables:

; $PAGE->navigation : This is the main navigation structure, it will contain items that will allow the user to browse to the other available pages.
; $PAGE->settingsnav : This is the settings navigation structure contains items that will allow the user to edit settings.
; $PAGE->navbar : The navbar is a special structure for page breadcrumbs.

==What the navigation is not==
The navigation is '''NOT''' the navigation block or the settings block! These two blocks were created to display the navigation structure. The navigation block looks at ''$PAGE->navigation'', and the settings block looks at ''$PAGE->settingsnav''. Both blocks interpret their data into an HTML structure and render it.

# The navigation is a back-end structure that is built behind the scenes and has no immediate method of display.
# The navigation and settings blocks display the back-end navigation structure but add nothing to it at all.
::In the [[model-view-controller pattern]], $PAGE->navigation, $PAGE->settingsnav, and $PAGE->navbar are the models, and the blocks are views.

The navbar is just the path to the active navigation or settings item. The navbar is not displayed by a block; instead it is added into the theme's layout files and displayed by the core renderer.

==How the navigation works==

The main navigation structure can be accessed through '''$PAGE->navigation'''. The navigation and settings are contextual in that they will relate to the page that the user is viewing. This is determined by other $PAGE object properties:
* '''$PAGE->context''' is a Moodle context that immediately outlines the nature of the page the user is viewing.
* '''$PAGE->course''' is the course the user is viewing. This is essential if the context is CONTEXT_COURSE or greater. However, it is also useful in other contexts such as CONTEXT_USER.
* '''$PAGE->cm''' is the course module instance. This is essential if the context is CONTEXT_MODULE or greater.
* '''$PAGE->url''' is used to match the active navigation item.

Nearly every page sets $PAGE->url through a call to '''$PAGE->set_url''' however not many explicitly set the context, course, or cm. When you call '''require_login''' with a course or cm it automatically calls the following:
<code php>
if ($cm) {
$PAGE->set_cm($cm, $course); // sets up global $COURSE
} else {
$PAGE->set_course($course);// sets up global $COURSE
</code>

A page will only be required to explicitly set a context, course, or cm under one of these conditions:
# '''require_login''' is NOT being called correctly
# The page is using CONTEXT_SYSTEM, CONTEXT_COURSECAT, or CONTEXT_USER (call '''$PAGE->set_context''' ).
# The page is using a course or cm but it is also using one of the above contexts (call '''$PAGE->set_course''' or '''$PAGE->set_cm''' ).

The navigation structure cannot be generated before the $PAGE object is configured. It is only generated when it is first used, either when something tries to access the structure or when code tries to add to it. The navigation is initialised in a specific order:
# Main navigation structure
# Settings navigation
# Navbar (does not need to be generated because of its simple contents and rendering)

==Extending the navigation==

===Code extension===
This method of extending is when the code arbitrarily extends the navigation during its execution. Extending the navigation through this means allows you to extend the navigation anywhere easily, however it will only be shown on pages where your extending code gets called (you should probably put it in a function within lib.php).

Navigation extensions that apply all the time (even when not on pages including your code) can be made by putting them in your plugin's settings.php file.

These examples are taken from the [http://moodle.org/mod/forum/discuss.php?d=152391 General Developer Forum: Moodle 2 - how to set up breadcrumbs for a module page]. It has further information that is well worth reading.
====Navigation====
This is extending the main navigation structure.
<code php>
$previewnode = $PAGE->navigation->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $previewnode->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>
The above lines of code adds a preview node to the bottom of the navigation and then adds a thingnode to the previewnode (adding a leaf to our tree).
The final line of code makes the thingnode active so that the navbar finds it however if the URL you give it is the same as the url you set for the page it will automatically be marked active and you won't need this call.

Next extending the navigation for the course.
For this you will need to know the course id and have called require_login($courseorid); so that the navigation is loaded for the course.
<code php>
$coursenode = $PAGE->navigation->find($courseid, navigation_node::TYPE_COURSE);
$thingnode = $coursenode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>
The new bit of code here really is the first line which simply finds the course node, to do this we give it the course id and the node type in this case TYPE_COURSE.
What we are doing here is relying on the navigation to generate the navigation up to the course and then just adding to the course.

Note that Moodle loads plugins in alphabetical order. Therefore plugin_b can find a node added by plugin_a but not the other way around.
====Settings navigation====
Adding to the settings navigation is very similar to navigation
<code php>
$settingnode = $PAGE->settingsnav->add(get_string('setting'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $settingnode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>

====Add Settings folder to navigation====

An example of a settings folder in a module can be see by navigating to Site administration / Plugins / Activity modules / Assignment.

[[File:assignmentmenu.png]]

An example of adding a navigation folder to a settings.php for a block with a link to the settings page and a external page is bellow.

<code php>
<?php

defined('MOODLE_INTERNAL') || die;

// Create folder / submenu in block menu, modsettings for activity modules, localplugins for Local plugins.
// The default folders are defined in admin/settings/plugins.php.
$ADMIN->add('blocksettings', new admin_category('blocksamplefolder',
get_string('pluginname', 'mod_sample')));

// Create settings block.
$settings = new admin_settingpage($section, get_string('settings', 'block_sample'));
if ($ADMIN->fulltree) {
$settings->add(new admin_setting_configcheckbox('block_sample_checkbox', get_string('checkbox', 'block_sample'),
get_string('checkboxdescription', 'block_kronoshtml'), 0));
}

// This adds the settings link to the folder/submenu.
$ADMIN->add('blocksamplefolder', $settings);
// This adds a link to an external page.
$ADMIN->add('blocksamplefolder', new admin_externalpage('block_sample_page', get_string('externalpage', 'block_sample'),
$CFG->wwwroot.'/blocks/sample/sample.php'));
// Prevent Moodle from adding settings block in standard location.
$settings = null;
</code>

====Navbar====
This is extending the settings navigation.
<code php>
$PAGE->navbar->ignore_active();
$PAGE->navbar->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'));
$PAGE->navbar->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
</code>
The above code tells the navbar to ignore what ever the active page was and just use what you add, at which point we add two items as shown.

===Plugin Callbacks===
These are specific functions that the navigation looks for and calls if they exist for the plugin, presently only three plugin types can extend the navigation through these call-backs.

Ideally all entries in "Administration / Site administration" tree should be done via settings.php files but sometimes it may be easier to directly modify the navigation structure created from the admin settings tree (such as when adding links to external pages).

====Module====
Modules have two call-back methods, first to extend the navigation, and second to extend the settings. These call-backs get called when ever the user is viewing a page within the module and should only extend the navigation for the module.
<code php>
function {modulename}_extend_navigation(${modulename}node, $course, $module, $cm)
function {modulename}_extend_settings_navigation($settings, ${modulename}node)
</code>

====Course Formats====
Course formats are able to completely redefine the way in which navigation is generated for a course, as well as this they also have several methods to ensure the navigation is generated correctly.

====Course Reports====
By default reports don't add themselves or anything else to the navigation however there is a call-back that can be implemented to allow them to do so.

====Local Plugins====
{{Moodle 2.9}}Local plugins have two call-back methods, first to extend the navigation, and second to extend the settings.
<code php>
function local_{pluginname}_extend_navigation(global_navigation $nav)
function local_{pluginname}_extend_settings_navigation(settings_navigation $nav, context $context)
</code>

In versions before Moodle 2.9, the supported callbacks have <tt>_extends_</tt> (not imperative mood) in their names. This was a consistency bug fixed in MDL-49643.

<code php>
function local_{pluginname}_extends_navigation(global_navigation $nav)
function local_{pluginname}_extends_settings_navigation(settings_navigation $nav, context $context)
</code>

====Course settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the course settings navigation. Prior to 3.0 only ''reports'' and ''admin tools'' could extend the course settings navigation.

<code php>
function <component>_extend_navigation_course(navigation_node $parentnode, stdClass $course, context_course $context);
</code>

====User settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the user settings navigation. Prior to 3.0 only ''admin tools'' could extend the user settings navigation.

<code php>
function <component>_extend_navigation_user_settings(navigation_node $parentnode, stdClass $user, context_user $context, stdClass $course, context_course $coursecontext);
</code>

====Category settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the category settings navigation.

<code php>
function <component>_extend_navigation_category_settings(navigation_node $parentnode, context_coursecat $context);
</code>

====Frontpage settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the frontpage settings navigation. Prior to 3.0 only ''admin tools'' could extend the frontpage settings navigation.

<code php>
function <component>_extend_navigation_frontpage(navigation_node $parentnode, stdClass $course, context_course $context);
</code>

====User profile====
{{Moodle 3.1}}
Any plugin implementing the following callback in lib.php can extend the user profile navigation.
<code php>
function <component>_extend_navigation_user(navigation_node $parentnode, stdClass $user, context_user $context, stdClass $course, context_course $coursecontext);
</code>

==FAQ's and troubleshooting==
'''Q.''' My page is on the navigation but it doesn't find it?

The first thing to do here is check the URL you are setting for the page. It should match the URL your page has within the navigation. If it doesn't you have two options, first change your '''$PAGE->set_url''' call, or second override the URL the navigation is using to find the active node as shown below:
<code php>
navigation_node::override_active_url(new moodle_url('/your/url/here.php', array('param'=>'value')));
</code>

==See also==

* [[Core APIs]]
* [https://moodle.org/mod/forum/discuss.php?d=170325&parent=753095 Forum discussion - adding navigation to local plugins]

[[Category:API]]

Course completion

2015-12-15T10:04:15Z

Davidbalch: Remove obsolete "Notifications" reference. Ref https://docs.moodle.org/dev/index.php?title=Course_completion&type=revision&diff=34956&oldid=8813

'''Note''': up to date information for users is available in the user documentation on [https://docs.moodle.org/en/Course_completion Course completion].

=Overview=
We need to flag when the "student" has finished a course. :-)

We need to allow several types of criteria to determine how a "student" can complete a course:
* '''Manual self completion''': A "student" can mark her/himself complete a course.
* '''Manual completion by''': An "admin", "teacher", "tutor", etc can mark a student complete for a course.
* '''Activity completion''': A "student" completes an activity, building on [https://docs.moodle.org/en/Development:Conditional_activities#Completion_tracking_2 Activity Completion] developed for 2.0 by Sam Marshall from OU.
* '''Course grade''': A "student" meets or exceeds a passing grade in the course.
* '''Date''': After a specified date all "students" are marked as completed in a course.
* '''Duration after enrolment''': After a specified amount of time after enrolment (e.g., 12 weeks), a "student" is automatically marked as complete in a course.
* '''Unenrol''': After being unenroled, a "student" is marked complete for the course. Useful for external enrolment plugins.

We need to record when and how a "student" meets each criteria in a course.

We need to regularly aggregate the results for the criteria, measure progress, and check to see if a "student" has completed a course.

We need to show:
* A "student" the necessary criteria to complete a course
* A "student" how s/he is progressing in a course along the necessary criteria
* A "teacher" how his/her students are progressing in a course and which students have completed it

=Settings=
==Site settings==
[https://docs.moodle.org/en/Development:Conditional_activities#Completion_tracking_2 Activity Completion] provides an "Enable completion tracking" setting (found in the Site Administration block's Advanced features / optional subsystems settings page) for activity completion. We need to change the setting's name and add another setting for course completion.

'''Proposed changes:'''
* Rename the setting "Enable activity completion tracking" (the setting will continue to allow activity completion to be enabled in all courses)
* Create a new setting named "Enable course completion tracking" (the setting will allow course completion to be enabled in all courses)

==Course settings==
[https://docs.moodle.org/en/Development:Conditional_activities#Completion_tracking_2 Activity Completion] provides a fieldset (named "Student progress") which contains a setting (named "Completion tracking") which enables/disables activity completion in a course. We need to rename the setting to describe activity completion and add a setting to enable course completion.

"Enable completion tracking" setting (found in the Site Administration block's Advanced features / optional subsystems settings page) for activity completion.

'''Proposed changes:'''
* Rename the setting "Completion tracking" to "Activity completion tracking" (the setting will continue to make activity completion features available in the courses)
* Create a new setting named "Course completion tracking" (the setting will make course completion features available in the course)

==Course completion settings==
When course completion is enabled in a course (see above), a menu item labeled "Completion" will appear in the course Administration block on the main course page. When a user clicks on the "Completion" link, the course completion admin page will display the criteria described below and in the mockup also below:

[[Image:Edit_course_completion_settings.png|thumb|600px|Edit course completion settings]]

===Criteria enabling===
We need to allow criteria to be enabled.

We need some rules about enabled criteria in a course:
* Each criteria (e.g., "Manual self completion", "Manual completion by", etc) can be enabled
* By default, all criteria are not enabled

===Criteria aggregation===
We need to define overall aggregation methods for the criteria type. We also need to a consistent set of aggregation methods for criteria types which have more than one possible option to determine an individual user's course completion:
* "Manual completion by" // more than one role can be enabled to determine if a student has completed the course
* "Activity completed" // more than one activity completion can be selected to determine if a student has completed the course

Aggregation methods:

{| border="1" cellpadding="2" cellspacing="0"
|'''Method'''
|'''Required to complete the criteria type'''
|'''Example'''
|'''Info'''

|-
|'''All'''
|All of the enabled child criteria must be completed
|Not applicable
|

|-
|'''Any'''
|Any one (1) of the enabled child criteria must be completed
|Not applicable
|

|}

===Criteria types===
====Manual self-completion====
'''Action:'''
* A "student" can manually indicate that s/he has completed a course via the course's [https://docs.moodle.org/en/Development:Course_completion#Block Completion progress block].
'''Tracked:'''
* The day/time when the "student" marked him/herself complete.

====Manual completion by====
'''Action:'''
* A user assigned to the role in the course will see a checkbox in the [https://docs.moodle.org/en/Development:Course_completion#Report Completion progress report], which will allow him/her to manually "Mark complete" each applicable student enrolled in the course.

'''Tracked:'''
* The roleid of the user who marked the "student" complete.
* The userid of the user who marked the "student" complete.
* The day/time when the user marked the "student" as complete in the course.

'''Notes:'''
# The Completion progress report will respect:
#* '''Separate groups:''' A "teacher" will only be able to see and mark complete students in her/his group(s) if separate groups is enabled.
#* '''Role assignments on the USER-level context:''' A "Tutor" or "Mentor" will only be able to see and mark complete users assigned to him/her.
# The criteria can be met only once by the role:
#* If more than one user is assigned to the role and has the capability of marking the user complete
#* After a "student" has been marked complete one time by a user in the role, the [https://docs.moodle.org/en/Development:Course_completion#Report Completion progress report] will not provide a checkbox in the "Mark complete" column when viewed by any user in the role in the course.
# We really be relying on role capabilities and permissions for this.

====Activities completed====
'''Action:'''
* A "student" will meet the criteria when completing the specified activity, per the activity's 'Activity Completion' settings.

'''Tracked:'''
* The cmid, module type, and activity/resource name for each activity.
* The day/time when the criteria was detected as complete.

'''Note:'''
# The list of activities/resources will contain:
#* Each activity/resource in the course with "Completion tracking" enabled within the activity/resource.
#* The type of each activity followed by the activity name (i.e., "[mod name] - [activity/resource name]"). See the mockup on this page (or for a basic example: "Quiz - Derivatives").
# If "Activity completion" is not enabled for the site, the "Activities completed" field set will not appear on the page.
# If "Activity completion" is enabled for the site and not enabled for the course, the "Activities completed" field set will appear and it will only contain this message:
#:''"Activity completion must be enabled for this course."''
# If "Activity completion" is enabled for the site and course, and there are no activities in the course, the "Activities completed" field set will appear and it will only contain this message:
#:''"Currently, there are no activities in this course"''
# If "Activity completion" is enabled for the site and course, and there are activities but none have activity completion enabled, the "Activities completed" field set will appear and it will only contain this message:
#:''"Currently, none of the activities in this course have defined activity completion settings."''

====Course grade====
'''Action:'''
* A "student" will meet the criteria when earning a total course grade above the passing grade.

'''Tracked:'''
* The day/time when the user's course grade was evaluated as having exceeded the passing grade.

'''Note:'''
* The passing grade can also be updated via the course's "Grade to pass" setting found in the Grader report's edit page for the top level category for the course.
* Once a student has completed the course, both the "Passing grade" setting on the course page and the "Grade to pass" setting in the top level category for the course will be locked. A message about locking will appear on the settings page for the top level category for the course.

====Date====
'''Action:'''
* A "student" enroled in the course will automatically meet the criteria after a specified date.

'''Tracked:'''
* The day/time when specified day was evaluated as having passed.

====Duration after enrolment====
'''Action:'''
* A "student" will meet the criteria after the specified number of days after his/her enrolment.

'''Tracked:'''
* The day/time when the "student" marked him/herself complete.

====Unenrolment====
'''Action:'''
* A "student" will meet the criteria when being unenroled from the course.

'''Tracked:'''
* The day/time when the "student" was unenroled from the course.

===Locking===
When the first student has completed the course, the course completion criteria settings will be locked. The course settings can be unlocked (via an "Unlock course completion options" button), however a warning message will be displayed stating that unlocking the settings requires deleting all prior course completion data for the course. Once the completion data is deleted, the settings become unlocked (i.e., un-greyed out).

This is consistent with activity completion in 2.0, in which activity completion settings are locked when a user first completes an activity. Activity completion settings can be unlocked after all completion activity is deleted.

==Activity settings==
If activity completion is enabled and activity completion is a criteria for course completion, then all activity completion settings will be locked once a student has completed the course. In this case, unlocking an activity's completion settings will require deleting both the activity's completion data and the course's completion data.

If an activity is being tracked for course completion, we should add a warning/confirmation screen when an "admin" attempts to delete it. The message should say, "[Activity name] is currently a criteria for course completion. Are you sure you want to delete it?" [Delete anyway] / [Cancel]. If the "admin" confirms, the activity will be deleted however completion data for users who completed it will still remain tracked.

Should the activity completion data remain?
Should the course completion data be re-aggregated?

=Data structures=
[[Image:Course_completion_data_model.png|thumb|400px|Course completion data model]]

===course===
The course table will require the following new fields. 'enablecompletion' will now be used for activity and course completion:

{| border="1" cellpadding="2" cellspacing="0"
!Field
!Type
!Default
!Info

|-
|'''completionnotify'''
|int(1)
|
|Notify users when they complete this course

|}

===course_completion_aggr_meth===
This new table will be populated with the aggregation method for "Overall criteria", "Manual completion by", and "Activities completed".

{| border="1" cellpadding="2" cellspacing="0"
!Field
!Type
!Default
!Info

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''course'''
|int(10)
|
|The id of the course that the course completion aggregation relates to

|-
|'''criteriatype'''
|int(20)
|null
|The criteria type's integer constant ('role', 'activity') or null if 'overall' course aggregation.

|-
|'''method'''
|int(1)
|1
|'1'='all', '2'='any', '3'='fraction', '4'='unit'.
|-

|'''value'''
|number(10)
|null
|null for 'all' and 'any', 0..1 for 'fraction', int > 0 for 'unit'
|}

===course_completion_criteria===
This new table will be populated with each criteria in each course for course completion:

{| border="1" cellpadding="2" cellspacing="0"
!Field
!Type
!Default
!Info

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''course'''
|int(10)
|
|The id of the course that the course completion criteria relates to

|-
|'''itemname''' (not implemented)
|varchar(100)
|null
|The name of the item (e.g. "Mark yourself complete", "Teacher marks you complete", "[Activity name]", "[postenrol] days after enrolment", "Official Date: [date]". Used for all item types except unenrol.

|-
|'''criteriatype'''
|int(20)
|
|The criteria type's integer constant ('self', 'role', 'mod', 'grade', 'enrolperiod', 'date', 'postenrol').

|-
|'''module'''
|varchar(100)
|null
|The name of the module (e.g., 'scorm', 'quiz', 'feedback'). Used only if criteriatype='mod'.

|-
|'''moduleinstance'''
|int(10)
|null
|The id of the activity/resource module or role. Used only if criteriatype='mod'.

|-
|'''enrolperiod'''
|int(10)
|null
|The number of seconds after enrolment. Used only if criteriatype='enrolperiod'.

|-
|'''date'''
|int(10)
|null
|The timestamp of the date for course completion. Used only if criteriatype='date'.

|-
|'''gradepass'''
|number(10)
|null
|The course grade required to complete this criteria. Used only if criteriatype='grade'.

|-
|'''role'''
|int(10)
|null
|The role id that can mark 'student's as complete in the course. Used only if criteriatype='role'.

|-
|'''lock''' (currently unused)
|int(10)
|null
|Date this criteria was locked
|}

===course_completion_crit_compl===
This new table will be populated with records for each user as they complete each course completion criteria.

{| border="1" cellpadding="2" cellspacing="0"
!Field
!Type
!Default
!Info

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''userid'''
|int(10)
|
|The id of the user who has completed the course

|-
|'''course'''
|int(10)
|
|The id of the completed course

|-
|'''criteriaid'''
|int(10)
|
|The id of the completion criteria this references

|-
|'''gradefinal'''
|number(10)
|null
|The final grade for the course (if referenced criteria type='grade').

|-
|'''unenroled'''
|int(10)
|null
|Timestamp when the user was unenroled (if referenced criteria type='unenrol').

|-
|'''deleted''' (currently unused)
|int(1)
|null
|The course was deleted

|-
|'''timecompleted'''
|int(10)
|null (should be notnull)
|Timestamp when the user completed the criteria
|}

===course_completions===
This table records a user's course completion state in a course (but not for individual criteria).

{| border="1" cellpadding="2" cellspacing="0"
!Field
!Type
!Default
!Info

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''userid'''
|int(10)
|
|The id of the user who has completed the course

|-
|'''course'''
|int(10)
|
|The id of the completed course

|-
|'''timeenrolled'''
|int(10)
|
|Timestamp when the user was enrolled in the course. In the case of multiple enrollments, the earliest timestamp for a current enrollment is used. If this is reported as 0, the current time is used instead.

|-
|'''timestarted'''
|int(10)
|
|Timestamp when the user first made progress in the course

|-
|'''timecompleted'''
|int(10)
|null
|Timestamp when the user completed the course

|}

=Evaluating completion=
Since the gradebook aggregation is performed via cron, it makes sense that course completion is also evaluated by cron.

This creates an issue in which the progress block will not instantly not show course completion after the necessary criteria has been met by a "student". However, this can be solved by adding some instructional text to say "may take a few minutes to update".

=Role capabilities=
{| border="1" cellpadding="2" cellspacing="0"
|'''Feature'''
|'''Description'''
|'''Capability'''

|-
|Progress block
|Mark self-complete in progress block
|block/progress:markselfcomplete

|-
|Progress report
|View course progress report
|coursereport/progress:view

|-
|Progress report
|Mark users complete in course progress report
|coursereport/progress:markcomplete

|}

=Course reporting=
==Completion progress report==
[[Image:Completion_report.png|thumb|600px|Course completion progress report]]

A course completion report is available when course completion is enabled.The report can be found via on "Reports" menu item link in the course Administration block and when "Completion tracking" is enabled for the site and course.

The report shows:
* A column for each of the activities/resources in the course with "Completion tracking" enabled"
* A row for each user enroled in the course
* The completion status for each activity

'''Proposed changes:'''
* Include in the report all enabled criteria for course completion (e.g., "Manual self completion", "Manual completion by", as well as the activities etc)
* Each user's status for completion of each criteria, indicated by a status icon
* Allow the completion admin page to determine which activities are shown in the report
* Allow the list of users to be sortable, searchable, and filterable (by group, groupings, and/or user profile fields).
* Allow user profile fields (standard and custom) can be added/removed as columns in the list.
* When rolling over the each icon, additional details (including the completion date) will display.

See the mockup to the right with all course completion criteria appearing (i.e., all criteria types have been enabled in a course).

As described further above, display rules for separate groups will apply. If separate groups is enabled for the course, a "teacher" will only see students and completion data for users in the group(s) that she/he is assigned to.

Options for exporting completion data to CSV, ODF or Excel will be available. Completion dates will be included in the export.

A column labeled "Mark complete" will appear containing a checkbox for each student if the user viewing the report is assigned to a role that is allowed to manually indicate that the students have completed the course.

Not shown in the mockup, however we should display the specified values under the applicable heading in the report for each of the following feilds:
* Period after enrolment
* Passing grade
* Date (for completion)

==Gradebook==
# If "Passing grade" is enabled as a criteria for course completion, a grader should have the option of seeing completion status (i.e., "complete" / "not complete") as a column in the grader report.
# If a user assigned to a role that is enabled for "Manual completion by", the user should have the option of manually indicating which students have completed the course, a "Mark complete" column will appear to the right of the "Course total" column with a checkbox for each student who has not yet completed the course.

We should also provide an option to show course completion status in gradebook exports. Field options will include:
* Completion status (e.g., "Complete", "Not complete")
* Completion date

==Completion progress block==
[[Image:Course_completion_progress_block.png|thumb|190px|Course completion progress block]]

If completion is enabled for the site and a course, a completion block will be available to be added to the course.

The block will allow a "student" to see:
* The completion criteria for completing the course
* His/her status for completion of each criteria (similar to the Completion progress report)
* His/her overall completion status for the course (complete / not complete)

If all of the enabled criteria are required, the introduction text should say:
:''"All of the criteria below needed"''

If any of the enabled criteria are required, the introduction text should say:
:''"Any of the criteria below needed"''

If the current user can self complete the course, the block will provide an "I've completed this course" button (if the user has not already marked him/herself complete).

Activity completion criteria/status (if enabled for course completion) should be included in the block. See [http://tracker.moodle.org/browse/MDL-16466 MDL-16466] ("Activities on the course page do not convey to student that completion is expected or available for the activity").

==User (course) profile==
Activity and course completion criteria/status data should appear in a user's "Outline report" and "Complete report" in the user profile area, which is being reworked for 2.0 separately from this spec.

=Site reporting=

==User (site) profile==
[[Image:Course_completion_user_profile_activity.png|thumb|400px|Mockup of the user profile page with Course completion report]]

Activity and course completion criteria/status data should appear in a user's profile area.

It would make sense for courses to be grouped by:
* Courses in progress
* Courses completed
* Courses not yet started

For each course, the required criteria and status should appear.

=Cron=
A cron function will check the criteria and update the course_completion_completions table as necessary. Here's a breakdown of the tasks for each criteria, and will need to be optimised for performance and scalability across all courses:

* '''Manual self completion:''' Cron not needed, performed directly from the Completion progress block.
* '''Manual completion by:''' Cron not needed, performed directly via the Completion progress report.
* '''Course grade:''' Compare the course grade to the passing grade.
* '''Unenrol:''' Compare course_completion->unenroled to role_assignments->timeend for the "student" role in the course.
* '''Date:''' Compare the current date to the specified date.
* '''Duration after enrolment:''' Compare the current date to the role_assignments->timestart + the specified period after enrolment.
* '''Activity completion:''' Evaluate the necessary records in the course_modules_completion table.
* '''Course completion:''' Aggregate the necessary fields in course_completion table, updating the timecompleted field with the current timestamp if the user has met the necessary criteria.

=Backup and restore=
* The new completion fields in the course table will be included in the backup.
* Entries in the course_completion_items, course_completion_aggregation_methods, and course_completion_notify tables for the course should also be included in the backup.
* When user data is included in a course backup, the backup will also include records in the course_completion_completions table for the course.

=Events=
The following course completion related events have been added to core:
* course_completed
** Triggered when a user completes a course. Event data is the full course_completions database record.
** Added in version 2.3.2

[[Category:Completion]]

Customising the theme user menu

2015-11-12T14:54:14Z

Davidbalch:

{{Template:Themes}}{{Moodle 3.0}}

As of 3.0, the [https://docs.moodle.org/29/en/Theme_settings#User_menu_items user menu] can be customised via an array of options, when it is called via <code>user_get_user_navigation_info()</code>.

Initially, only the size of the user's avatar picture can be changed (from the default of 35px square), using the <code>avatarsize</code> key with a new size.

<code php>
user_get_user_navigation_info($user, $this->page, array('avatarsize' => 85));
</code>

Unfortunately, to change the one line that calls <code>user_get_user_navigation_info()</code>, the whole of <code>core_renderer::user_menu()</code> must be overridden:

In '''/themes/<yourtheme>/renderers.lib'''...
<code php>
public function user_menu($user = null, $withlinks = null, $loginlogo = null) {

// Lots of code copied from lib/outputrenderers.php...

// Get some navigation opts.
$opts = user_get_user_navigation_info($user, $this->page, array('avatarsize' => 85));

$avatarclasses = "avatars";
$avatarcontents = html_writer::span($opts->metadata['useravatar'], 'avatar current');
$usertextcontents = $opts->metadata['userfullname'];

// Lots more code copied from lib/outputrenderers.php...

}
</code>

NB: The image size in the browser may actually be set via CSS, as the pixel size of the image is rounded up to one of a few hard-coded sizes - see MDL-50420.

==See also==
* MDL-50839 - Allow themes to set User menu avatar size
* [[Overriding a renderer]]

[[Category:Themes]]
[[es:Personalizando el menú de usuario del tema]]

Moodle 3.0 release notes

2015-10-30T10:27:18Z

Davidbalch:

{{Work in progress}}

[[Releases]] > {{FULLPAGENAME}}

Release date: Monday, 9th November 2015

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.0%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.0].

See our [https://docs.moodle.org/30/en/New_features New Features page] for a more user-friendly introduction to Moodle 3.0 with screenshots.

If you are upgrading from previous version, make sure to read the [https://docs.moodle.org/30/en/Upgrading Upgrading] documentation.

==Server requirements==

These are just the minimum supported versions. We recommend keeping all of your software up-to-date.

* Moodle upgrade: Moodle 2.2 or later (if upgrading from earlier versions, you must upgrade to 2.2.11 as a first step)
* PHP version: minimum PHP 5.4.4 (always use latest PHP 5.4.x or 5.5.x on Windows - http://windows.php.net/download/), PHP 7 is NOT supported
* Ghostscript should be installed for pdf annotation.

=== Database requirements ===

Moodle supports the following database servers. Again, version numbers are just the minimum supported version. We recommend running the latest stable version of any software.

{| class="nicetable"
|-
! Database
! Minimum version
! Recommended
|-
| [http://www.postgresql.org/ PostgreSQL]
| 9.1
| Latest
|-
| [http://www.mysql.com/ MySQL]
| 5.5.31
| Latest
|-
| [https://mariadb.org/ MariaDB]
| 5.5.31
| Latest
|-
| [http://www.microsoft.com/en-us/server-cloud/products/sql-server/ Microsoft SQL Server]
| 2008
| Latest
|-
| [http://www.oracle.com/us/products/database/overview/index.html Oracle Database]
| 10.2
| Latest
|}

==Client requirements==

=== Browser support ===

{| class="nicetable"
|-
! Browser
! Minimum version
! Recommended version
! Notes
|-
| [https://www.google.com/intl/en_au/chrome/browser/ Google Chrome]
| 30.0
| Latest
|
|-
| [http://www.mozilla.org/en-US/ Mozilla Firefox]
| 25.0
| Latest
|
|-
| [http://www.apple.com/safari/ Apple Safari]
| 6
| Latest
|
|-
| [http://windows.microsoft.com/en-AU/internet-explorer/download-ie Microsoft Internet Explorer]
| 9
| Latest
| Version 10 is required for drag-and-drop upload of content from outside the browser into Moodle
|}

==Major features==

===Highlights===

* MDL-29801 - Allow users to delete personal messages
* MDL-27177 - Allow students to see each other's contact details in full profile without global permission if they are able to see each other's course profile
* MDL-46455 - Re-introduce backup/restore functionality with new logging system
* MDL-46878 - Reset Dashboard for all users after changing the default dashboard

===Quiz===

* MDL-47494 - New question types from the OU - [https://docs.moodle.org/30/en/Select_missing_words_question_type Select missing words], [https://docs.moodle.org/30/en/Drag_and_drop_into_text_question_type Drag and drop into text], [https://docs.moodle.org/30/en/Drag_and_drop_onto_image_question_type Drag and drop onto image] and [https://docs.moodle.org/30/en/Drag_and_drop_markers_question_type Drag and drop markers]
* MDL-38214 - Add MCS, MCVS, MCHS Cloze subquestion types
* MDL-50127 - By default the list of question types should be sorted with common ones at the top
* MDL-29771 - Interactive behaviour should show number of tries left in the Try again state

===Forum===

* MDL-49682 - Make forum email template editable
* MDL-46321 - Uninformative error when moving forum without first selecting destination
* MDL-50993 - Timed discussions are now displayed to students in a logical order
* MDL-50430 - Add number of subscribers to forum subscriber list

===Assignment===

* MDL-49176 - Assigment marking guide 'flattens' instructions for markers and students
* MDL-49515 - Upgrade FPDI library in assignfeedback_editpdf to 1.5.4 to fix problems with PDF annotator on some files
* MDL-50283 - Improve Rubric interface to include the ability to duplicate rows

===Other activity modules===

* MDL-49028 - Wiki: Option to delete pages during course reset
* MDL-40836 - File resource: New [https://docs.moodle.org/30/en/File_resource_settings file resource setting] option to display upload/modified date
* MDL-26501 - Glossary: Do not allow to browse by author if author is never displayed
* MDL-50673 - Workshop: display all participants on "Submisstion phase" page in a table
* MDL-50664 - Database: add setting to disallow managing of own entries after approval
* MDL-50658 - LTI: Add support for LTI Memberships service
* MDL-49581 - Lesson: Remove high scores list feature
* MDL-49882 - Lesson: Essay questions are not imported into the lesson Module
* MDL-50720 - Database: Highlight database entries that are not yet approved.

===User interface and usability improvements===

* MDL-51051 - Rename 'Categories and items' to 'Gradebook setup' and add link
* MDL-51250 - Show default section name when editing section details with default checkbox being checked
* MDL-49984 - Add visual blocks outlines to My profile page to help separate information
* MDL-48947 - Collect all course section editing buttons under one "Edit" dropdown
* MDL-51087 - Use client-side validation in the signup form
* MDL-50113 - Improve display of long user and course names in Messaging
* MDL-50919 - Simplify the Manage tags page, allow to quickly change name, flag and official status of the tags
* MDL-51013 - Navbar button should appear for smaller screens only when the custom menu or language menu is not empty
* MDL-51260 - Use the new autocomplete form field for tags
* MDL-51296 - Add title to page when adding blog post
* MDL-38763 - Permission override UI should use JS confirmation
* MDL-29763 - Add description to Portfolio settings page

===Atto editor===

* MDL-45515 - New table editing features in Atto editor
* MDL-49732 - Keyboard interaction for hyperlink in Atto (Ctrl+K)
* MDL-50936 - More Atto Math Equation buttons (sum, sqrt, int, etc.)
* MDL-50142 - Text editor preferences help pop-up

===Enrolments===

* MDL-30674 - Set guest access key from enrolment methods page
* MDL-30157 - Allow users to start manual enrolments right now
* MDL-49746 - Allow to sort enrolled users page by last course access
* MDL-48074 - Group filter in enrolments list should have option "not in any group"

===Administration===

* MDL-49329 - Multiple improvements in the plugins installation/update system including ability to install several plugins at the same time
* MDL-49280 - New configuration setting to allow duplicate email addresses
* MDL-51330 - Show scheduled tasks component in the cron log
* MDL-51261 - Upgrade key - mechanism to protect anonymous web access to upgrade screens
* MDL-50602 - New settings in [https://docs.moodle.org/30/en/Automated_course_backup Automated backup setup] for deleting older backups and keeping a minimum number of backups
* MDL-48438 - Add real name to email about login failures
* MDL-30960 - New option in email settings to specify SSL or TLS (SMTPSecure property of PHPMailer)
* MDL-46623, MDL-51824 - CAS and LDAP: Replace CLI script to synchronise users with a scheduled tasks
* MDL-39319 - Allow administrator to uninstall several languages in one single action
* MDL-50155 - Move and rename "Common activities settings" link to be under "Manage activities" for consistency
* MDL-50631 - Display Moodle ASCII logo in CLI installer
* MDL-46167 - New option for CLI installation: skip database
* MDL-50572 - Disable Youtube repository by default since it requires setting up
* MDL-51739 - Lock theme selector UI when $CFG->theme is hardcoded in config.php
* MDL-51478 - Enable Mobile services by default
* MDL-19748 - Do not allow to edit tags in the default authenticated user role
* MDL-46398 - Make HTML5 video the default player for capable videos

===Other improvements===

* MDL-51132 - Introduce course tagging as a replacement for user-course-tagging in the "Tags" block. See [https://docs.moodle.org/30/en/Tags_block#Course_tagging_changes_in_Moodle_3.0 upgrade documentation]
* MDL-41042 - Course contacts shown in course listings no longer lag by an hour
* MDL-44273 - Back-off strategy for RSS feeds
* MDL-45981 - CAS Auth Config needs way to specify that curl should use SSLv3.
* MDL-49891 - Add description meta to frontpage
* MDL-25451 - Go straight to "Permissions" from block context menu instead of "Assign roles" if theya are not available
* MDL-50647 - Add 'not in group' section to group overview page
* MDL-50956 - Allow main menu block to be displayed "throughout the entire site"
* MDL-28954 - Allow images and embedded files in the cohort descriptions
* MDL-50371 - Use $CFG->gradepointdefault for new manual gradeitems and grade categories

==Security issues==

A number of security related issues were resolved. Details of these issues will be released after a period of approximately one week to allow system administrators to safely update to the latest version.

==For developers==

* MDL-46455 - Events must define fields mappings in order to be correctly restored ([https://docs.moodle.org/dev/Event_2#Backup.2Frestore documentation])
* MDL-50125 - Allow all plugins to inject links in the preferences page
* MDL-51247 - Revive / refresh / rebuild the autocomplete mform element.
* MDL-50839 - Allow themes to set User menu avatar size ([https://docs.moodle.org/dev/Customising_the_theme_user_menu documentation])
* MDL-48494 - Make $plugin->component required for all plugins
* MDL-43896 - Drop support for $module in version.php files for Moodle 3.0
* MDL-50645 - Cache the list of available callbacks per plugin
* MDL-33564 - rss_error() should return a proper HTTP response code
* MDL-37864 - New method to add help icons to the sortable table headers ([https://docs.moodle.org/dev/lib/tablelib.php documentation])
* MDL-51737 - Add ability to detect MS Edge in our browser sniffing code
* MDL-51213 - external_format_text should be safe to call from web or webservice ([https://docs.moodle.org/dev/How_to_contribute_a_web_service_function_to_core documentation])
* MDL-51413 - Add an additional return field in get_forums_by_courses in order to specify if the current user can create discussions
* MDL-51217 - Using recaptcha is not possible outside auth_email plugin.
* MDL-51107 - Add a callback to inject nodes in the category settings navigation
* MDL-50891 - is_web_crawler should be moved to useragent class
* MDL-50453 - Replace reserved word usage from \core\progress\null (PHP7)
* MDL-50009 - Prevent scheduled tasks from leaving unfinished db transactions
* MDL-49821 - Some Web Services miss checks for guest and deleted users
* MDL-50926 - Upgrade to phpunit 4.x
* MDL-50491 - New format_text option to exclude particular filters
* MDL-50783 - Allow some ajax external functions to be called without a session
* MDL-50150 - Add "Blocks" feature to JS and PHP mustache engines ([https://docs.moodle.org/dev/Templates#Blocks_.28Moodle_3.0_onwards.29 documentation])

[[Category:Release notes]]
[[Category:Moodle 3.0]]

[[fr:Notes de mise à jour de Moodle 3.0]]
[[es:Notas de Moodle 3.0]]

Customising the theme user menu

2015-10-30T10:24:47Z

Davidbalch: Add page for MDL-50839

{{Template:Themes}}{{Moodle 3.0}}

As of 3.0, the [https://docs.moodle.org/29/en/Theme_settings#User_menu_items user menu] can be customised via an array of options, when it is called via <code>user_get_user_navigation_info()</code>.

Initially, only the size of the user's avatar picture can be changed (from the default of 35px square), using the <code>avatarsize</code> key with a new size.

<code php>
user_get_user_navigation_info($user, $this->page, array('avatarsize' => 85));
</code>

Unfortunately, to change the one line that calls <code>user_get_user_navigation_info()</code>, the whole of <code>core_renderer::user_menu()</code> must be overridden:

In '''/themes/<yourtheme>/renderers.lib'''...
<code php>
public function user_menu($user = null, $withlinks = null, $loginlogo = null) {

// Lots of code copied from lib/outputrenderers.php...

// Get some navigation opts.
$opts = user_get_user_navigation_info($user, $this->page, array('avatarsize' => 85));

$avatarclasses = "avatars";
$avatarcontents = html_writer::span($opts->metadata['useravatar'], 'avatar current');
$usertextcontents = $opts->metadata['userfullname'];

// Lots more code copied from lib/outputrenderers.php...

}
</code>

NB: The image size in the browser may be enforced via CSS, with the pixel size of the image rounded up to one of a few hard-coded sizes - see MDL-50420.

==See also==
* MDL-50839 - Allow themes to set User menu avatar size
* [[Overriding a renderer]]

[[Category:Themes]]

HTML5 player

2015-03-10T11:41:35Z

Davidbalch: Fix misaligned columns in license row

{{Work in progress}}
{{Infobox Project
|name = HTML5 Player with flash fallback
|state = In Development
|tracker = https://tracker.moodle.org/browse/MDL-38158
|discussion = https://moodle.org/mod/forum/discuss.php?d=222753#p1110024
|assignee = [https://tracker.moodle.org/secure/ViewProfile.jspa?name=kabalin Ruslan Kabalin]
}}
{{Moodle 2.x}}

== Project goals ==

The purpose of this document is to choose HTML5 player with flash fallback for integration in Moodle and plan its implementation.

The aim of this change is to reach a consistent look of the player among different platforms and browsers, as well as making sure that player starts using flash if html5 is not supported by browser for the given format. Another aim is to improve accessibility and usability, enhance customisation.

== Considerations ==

* Usability of the player - is it easy to use it and intuitively understand how to use controls?
* Accessibility of the player - possibility of keyboard navigation, subtitles, support?
* Appearance of the player - can its interface be modified, themes support, RTL?
* Consistency among browsers - does player look the same?
* Audio support - can player handle HTML5 <audio> tag?
* Mobile platforms support - does player also work on iOS and Android?
* Streaming media support (including adaptive-bitrate delivery) - can player handle RTMP, Apple HLS, Adobe HDS, Microsoft HSS?
* Plugins support - can we use or develop community plugins easily?
* Embedding support - so users could post media content outside Moodle, if permitted.
* Maintainability of the links between the player and Moodle - how much work will we need to do every time we upgrade?

== Candidates ==

* [http://flowplayer.org/ Flowplayer HTML5]
* [http://www.videojs.com/ Video.JS]
* [http://www.projekktor.com/ Projekktor]
* [http://mediaelementjs.com/ MediaElement.js]
* ?Are there other alternatives?

== Comparison Matrix ==

{| class="nicetable"
|-
!
! [[#Flowplayer_HTML5|Flowplayer HTML5]]
! [[#Video.JS|Video.JS]]
! [[#Projekktor|Projekktor]]
! [[#MediaElement.js|MediaElement.js]]
! No Player
|-
! Accessible Player:
| colspan="4"|
|-
!
* Keyboard control
| Yes
| No
| Yes (configurable)
| Yes
| unknown
|-
!
* Subtitles support
| Yes
| Yes
| Yes (via plugin)
| Yes
| Yes (see http://caniuse.com/webvtt)
|-
!
* Touch interface
| Yes
| Yes
| Yes
| Yes
| Yes
|-
! Appearance:
| colspan="4"|
|-
!
* Skins
| Yes (via CSS)
| Yes (via CSS)
| Yes (via CSS)
| Yes (via CSS)
| No
|-
!
* CSS customisation
| Yes
| Yes
| Yes
| Yes
| unknown
|-
!
* RTL support
| Yes
| No
| No
| Unknown (CSS, so I guess so...)
| Unknown
|-
! Mobile platforms:
| colspan="4"|
|-
!
* iOS
| Yes
| No
| Yes
| Yes
| Yes
|-
!
* Android
| Yes
| No
| Yes
| Yes
| Yes
|-
! Streaming protocols:
| colspan="4"|
|-
!
* RTMP
| Yes
| Yes
| Yes (via playlist)
| Yes
| No
|-
!
* Adaptive HTTP
| HLS
| HLS (via plugin)
| HLS (via playlist)
| HLS
| Only in Chrome so far (Media Source Extension)
|-
! Audio player
| No
| Yes
| Yes
| Yes
| Yes
|-
! style="border-bottom: 2px solid;" | Embedding support
| style="border-bottom: 2px solid;" | Yes (configurable)
| style="border-bottom: 2px solid;" | Yes (via addThis plugin)
| style="border-bottom: 2px solid;" | Yes (via plugin)
| style="border-bottom: 2px solid;" | Yes
| style="border-bottom: 2px solid;" | No
|-
! License
| GPL v3 (with additional terms)
| Apache 2
| GPL v3
| MIT
| no extra code needed
|-
! JS library
| jQuery
| -
| jQuery
| jQuery
| none required
|-
! Plugins infrastructure
| No
| Yes
| Yes
| Yes
| No
|-
! Flash fallback player
| Flowplayer Flash
| video-js flash
| StobeMediaPlayback (but can be jarisplayer or some other).
| Flash and Silverlight (for .wmv support) fallback, used to provide the HTML5 video/audio elements.
| The Video tag can contain fallback content (e.g. Flash object) for browsers that don't support it at all (http://camendesign.com/code/video_for_everybody), but not based on codec support.
|-
! API
| Yes (plus window.flowplayer object)
| Yes
| Yes
| Yes
| Yes
|-
|}

=== Flowplayer HTML5 ===

'''Pros:'''
* Good looking player, resembles existing flash flowplayer in Moodle (with "functional" skin)
* Extensive customisation (via CSS3 skins and configuration object)
* Streaming support (RTMP, HLS)
* Good accessibility features
* Configurable embedding functionality
* Existing flash flowplayer can be configured for fallback (the appearance of player will not be affected).

'''Cons:'''
* Require jQuery for functioning
* Flowplayer logo remains on screen

'''Technical notes (lessons learned from the prototypes)'''
* Player initialisation is done using wrapper around <video>.
* width and height attributes in video tag are ignored, player size is configured via wrapper size only.
* RTMP server connection is configured via data-rtmp attribute in wrapper or player init config parameter, actual path the file specified in src attribute of source item.
* <source type="video/flash"... dummy MIME type to force using plash player for whatever content.

'''Missing features'''
* Plugins infrastructure
* No audio support

=== Video.JS ===

'''Pros:'''
* No logo on screen.
* Extensive API.
* No extra JS library needed.
* Many plugins.

'''Cons:'''
* Poor documentation
* RTMP requires non-standard MIME.
* Android and iOS override Video.JS with own player, when not overridden, content is not playing.
* No RTL.
* HLS support via plugin (many files to include, external contributor see https://github.com/videojs/videojs-contrib-hls).

'''Technical notes (lessons learned from the prototypes)'''
* Player initialisation is done using <video> tag directly (no wrapper needed).
* RTMP server connection and path specified as single URI in src attribute of source item, '&' character is used as server connection and path divider.

'''Missing features'''
* Embedded HLS support.

=== MediaElement.js ===

'''Pros:'''
* Flash fall-forward - uses Flash/Silverlight to provide the HTML5 MediaElement API.
* Consistent HTML/CSS Player
* No logo on screen.

'''Cons:'''
* ...

'''Technical notes (lessons learned from the prototypes)'''

* ...

'''Missing features'''

* ...

=== Projekktor ===

'''Pros:'''
* No logo on screen.
* Well documented API.
* Media RSS support.
* Possibility to choose flash player for fallback (included by default are StrobeMediaPlayback and Jarisplayer, both Open Source).
* Platform preference order selection (e.g. browser, ios, android, flash, native).

'''Cons:'''
* Uses flash where it is not supposed to (e.g. mp4 in Chrome).
* Issues on ios and android (suggests to download file when play button is pressed).
* RTMP only work if defined via playlist rather than in <source> tags.
* Subtitles plugin is not free.

'''Technical notes (lessons learned from the prototypes)'''
* Player initialisation is done using <video> tag directly (no wrapper needed).
* Make sure <video> tag has class attribute with 'projekktor' value (even if you initialise it by ID of the element), player will not work properly otherwise.

'''Missing features'''

=== HTML5 browser native ===

'''Pros:'''
* Simple

'''Cons:'''
* IE8 has no support

'''Technical notes'''
*

'''Missing features'''

== Cross-browser support ==

=== Method ===
Compatibility checks were done manually by accessing the sample page using different browsers and platforms. Sample page contained the list of identical player instances, initialised for each <video> definition with a <source> of particular format: mp4, webm, ogg, flv. Streaming support was checked by setting up a <video> container with two sources of the same video, one was HLS (Apple HTTP Live Streaming) stream for browsers and platforms that support html5 video streaming, another one was RTMP which is played using flash engine and supposed to be used in case if HLS is not supported.

=== Sample Pages ===

* [https://dev.mle.lancs.ac.uk/videotest/players.php?player=flowplayer Flowplayer HTML5] version 5.4.6.
* [https://dev.mle.lancs.ac.uk/videotest/players.php?player=videojs Video.JS] version 4.4.1.
* [https://dev.mle.lancs.ac.uk/videotest/players.php?player=projekktor Projekktor] version 1.3.09.
* [https://dev.mle.lancs.ac.uk/videotest/players.php?player=mediaelementjs MediaElement.js] version 2.6.14
* [https://dev.mle.lancs.ac.uk/videotest/players.php?player=native Native browser support].

=== Source ===

Source of testing page is hosted on [https://github.com/kabalin/test-html5-players/blob/master/players.php github]. The actual source of the html page can be viewed in browser.

=== Discussion ===

The players comparison that has been carried out demonstrated that "least hassle" player is Flowplayer. Despite some drawbacks listed in [[#Flowplayer_HTML5|corresponding section above]], it is clearly a winner as it works as expected and according to documentation for all browsers and platforms I had chance to test it. This is the only player that supports RTL layout, display platform incompatibility message prior to attempt to play, and was simple to configure (no undocumented tricks that I had to figure out to make it work). Both VideoJS and Projekktor do now perform properly in all cases. Among those two, I personally prefer Projekktor more for its extensive API, plugins infrastructure and configuration flexibility. However problems on mobile platforms and flash fallback inconsistency make them unreliable at this stage.

=== Compatibility results ===

The table was populated using Flowplayer as others do not perform good enough with some formats and platforms, e.g. VideoJS allow mobile platform player to override itself, Projekktor does not always use HTML5 where browser clearly can handle it (supported in native mode and Flowplayer).

{| class="nicetable"
|-
! Browser
! mp4
! webm
! ogg
! flv
! RTMP/HLS*
|-
! Windows 7
| colspan="5"|
|-
!
* Chrome 33.0.1750.117
| html5
| html5
| html5
| flash
| flash
|-
!
* Firefox 27.0.1
| html5
| html5
| html5
| flash
| flash
|-
!
* Opera 12.16
| flash
| html5
| -
| flash
| flash
|-
!
* Safari 5.1.7
| flash
| -
| -
| flash
| flash
|-
!
* Internet Explorer 11.0.9600.x
| html5
| -
| -
| flash
| flash
|-
! Linux (Debian Wheezy)
| colspan="5"|
|-
!
* Chrome 33.0.1750.115
| html5
| html5
| html5
| flash
| flash
|-
! OSX 10.9
| colspan="5"|
|-
!
* Safari 7.0 (9537.71)
| html5
| -
| -
| flash
| html5
|-
!
* Chrome 33.0.1750.117
| html5
| html5
| html5
| flash
| flash
|-
! Android 4.2.2 phone (CyanogenMod, no flash)
| colspan="5"|
|-
!
* Chrome 32.0.1700.99
| html5
| html5
| -
| -
| -
|-
!
* Browser 4.2.2 (com.android.browser)
| html5
| html5
| -
| -
| html5
|-
! Android 4.2.2 tablet (GalaxyTab2, flash app 11.1.115.36)
| colspan="5"|
|-
!
* Chrome 32.0.1700.99
| html5
| html5
| -
| -
| -
|-
!
* Browser 4.2.2 (com.android.browser)
| html5
| html5
| -
| flash
| html5
|-
!
* Opera 19.0.1340.x
| html5
| html5
| -
| -
| -
|-
! iPhone 4S (6.1.3)
| colspan="5"|
|-
!
* Safari
| html5
| -
| -
| -
| html5
|-
! iPad 4 (7.0.6)
| colspan="5"|
|-
!
* Safari
| html5
| -
| -
| -
| html5
|-
|}
* For HLS/RTMP, html5 in the table means HLS has been used, flash means player fell back and used RTMP.

== Sub Tasks ==

In initial stage FlowPlayer HTML5 (or any other) will handle all existing HTML5 Video extensions as per core_media_player_html5video class, plus m3u8 (HLS). It will also be possible optionally to make flash files handled by HTML5 Video player as well (possibility of using existing flash FlowPlayer for flv files will remain).

== Mock-Ups/Prototypes ==

See [[#Sample_Pages|Sample pages]] section.

== Workaround ==

As intermediate solution, if you require player consistency throughout all browsers and platforms, you may consider using JW Player filter: https://github.com/lucisgit/moodle-filter_jwplayer Notice, that JW Player is not free for commercial use.

== Related Tracker Issues ==
* MDL-38158

== Useful links ==
* http://praegnanz.de/html5video/
* http://html5video.org/wiki/HTML5_Video_Player_Comparison
* http://www.streamingmedia.com/Articles/Editorial/Featured-Articles/Choosing-a-Video-Player-Features-and-Specs-for-the-Top-Five-94188.aspx

[[Category:Project]]

HTML5 player

2015-03-09T17:17:41Z

Davidbalch: Add MediaElement.js

{{Work in progress}}
{{Infobox Project
|name = HTML5 Player with flash fallback
|state = In Development
|tracker = https://tracker.moodle.org/browse/MDL-38158
|discussion = https://moodle.org/mod/forum/discuss.php?d=222753#p1110024
|assignee = [https://tracker.moodle.org/secure/ViewProfile.jspa?name=kabalin Ruslan Kabalin]
}}
{{Moodle 2.x}}

== Project goals ==

The purpose of this document is to choose HTML5 player with flash fallback for integration in Moodle and plan its implementation.

The aim of this change is to reach a consistent look of the player among different platforms and browsers, as well as making sure that player starts using flash if html5 is not supported by browser for the given format. Another aim is to improve accessibility and usability, enhance customisation.

== Considerations ==

* Usability of the player - is it easy to use it and intuitively understand how to use controls?
* Accessibility of the player - possibility of keyboard navigation, subtitles, support?
* Appearance of the player - can its interface be modified, themes support, RTL?
* Consistency among browsers - does player look the same?
* Audio support - can player handle HTML5 <audio> tag?
* Mobile platforms support - does player also work on iOS and Android?
* Streaming media support (including adaptive-bitrate delivery) - can player handle RTMP, Apple HLS, Adobe HDS, Microsoft HSS?
* Plugins support - can we use or develop community plugins easily?
* Embedding support - so users could post media content outside Moodle, if permitted.
* Maintainability of the links between the player and Moodle - how much work will we need to do every time we upgrade?

== Candidates ==

* [http://flowplayer.org/ Flowplayer HTML5]
* [http://www.videojs.com/ Video.JS]
* [http://www.projekktor.com/ Projekktor]
* [http://mediaelementjs.com/ MediaElement.js]
* ?Are there other alternatives?

== Comparison Matrix ==

{| class="nicetable"
|-
!
! [[#Flowplayer_HTML5|Flowplayer HTML5]]
! [[#Video.JS|Video.JS]]
! [[#Projekktor|Projekktor]]
! [[#MediaElement.js|MediaElement.js]]
! No Player
|-
! Accessible Player:
| colspan="4"|
|-
!
* Keyboard control
| Yes
| No
| Yes (configurable)
| Yes
| unknown
|-
!
* Subtitles support
| Yes
| Yes
| Yes (via plugin)
| Yes
| Yes (see http://caniuse.com/webvtt)
|-
!
* Touch interface
| Yes
| Yes
| Yes
| Yes
| Yes
|-
! Appearance:
| colspan="4"|
|-
!
* Skins
| Yes (via CSS)
| Yes (via CSS)
| Yes (via CSS)
| Yes (via CSS)
| No
|-
!
* CSS customisation
| Yes
| Yes
| Yes
| Yes
| unknown
|-
!
* RTL support
| Yes
| No
| No
| Unknown (CSS, so I guess so...)
| Unknown
|-
! Mobile platforms:
| colspan="4"|
|-
!
* iOS
| Yes
| No
| Yes
| Yes
| Yes
|-
!
* Android
| Yes
| No
| Yes
| Yes
| Yes
|-
! Streaming protocols:
| colspan="4"|
|-
!
* RTMP
| Yes
| Yes
| Yes (via playlist)
| Yes
| No
|-
!
* Adaptive HTTP
| HLS
| HLS (via plugin)
| HLS (via playlist)
| HLS
| Only in Chrome so far (Media Source Extension)
|-
! Audio player
| No
| Yes
| Yes
| Yes
| Yes
|-
! style="border-bottom: 2px solid;" | Embedding support
| style="border-bottom: 2px solid;" | Yes (configurable)
| style="border-bottom: 2px solid;" | Yes (via addThis plugin)
| style="border-bottom: 2px solid;" | Yes (via plugin)
| style="border-bottom: 2px solid;" | Yes
| style="border-bottom: 2px solid;" | No
|-
! License
| GPL v3 (with additional terms)
| Apache 2
| GPL v3
| no extra code needed
| MIT
|-
! JS library
| jQuery
| -
| jQuery
| jQuery
| none required
|-
! Plugins infrastructure
| No
| Yes
| Yes
| Yes
| No
|-
! Flash fallback player
| Flowplayer Flash
| video-js flash
| StobeMediaPlayback (but can be jarisplayer or some other).
| Flash and Silverlight (for .wmv support) fallback, used to provide the HTML5 video/audio elements.
| The Video tag can contain fallback content (e.g. Flash object) for browsers that don't support it at all (http://camendesign.com/code/video_for_everybody), but not based on codec support.
|-
! API
| Yes (plus window.flowplayer object)
| Yes
| Yes
| Yes
| Yes
|-
|}

=== Flowplayer HTML5 ===

'''Pros:'''
* Good looking player, resembles existing flash flowplayer in Moodle (with "functional" skin)
* Extensive customisation (via CSS3 skins and configuration object)
* Streaming support (RTMP, HLS)
* Good accessibility features
* Configurable embedding functionality
* Existing flash flowplayer can be configured for fallback (the appearance of player will not be affected).

'''Cons:'''
* Require jQuery for functioning
* Flowplayer logo remains on screen

'''Technical notes (lessons learned from the prototypes)'''
* Player initialisation is done using wrapper around <video>.
* width and height attributes in video tag are ignored, player size is configured via wrapper size only.
* RTMP server connection is configured via data-rtmp attribute in wrapper or player init config parameter, actual path the file specified in src attribute of source item.
* <source type="video/flash"... dummy MIME type to force using plash player for whatever content.

'''Missing features'''
* Plugins infrastructure
* No audio support

=== Video.JS ===

'''Pros:'''
* No logo on screen.
* Extensive API.
* No extra JS library needed.
* Many plugins.

'''Cons:'''
* Poor documentation
* RTMP requires non-standard MIME.
* Android and iOS override Video.JS with own player, when not overridden, content is not playing.
* No RTL.
* HLS support via plugin (many files to include, external contributor see https://github.com/videojs/videojs-contrib-hls).

'''Technical notes (lessons learned from the prototypes)'''
* Player initialisation is done using <video> tag directly (no wrapper needed).
* RTMP server connection and path specified as single URI in src attribute of source item, '&' character is used as server connection and path divider.

'''Missing features'''
* Embedded HLS support.

=== MediaElement.js ===

'''Pros:'''
* Flash fall-forward - uses Flash/Silverlight to provide the HTML5 MediaElement API.
* Consistent HTML/CSS Player
* No logo on screen.

'''Cons:'''
* ...

'''Technical notes (lessons learned from the prototypes)'''

* ...

'''Missing features'''

* ...

=== Projekktor ===

'''Pros:'''
* No logo on screen.
* Well documented API.
* Media RSS support.
* Possibility to choose flash player for fallback (included by default are StrobeMediaPlayback and Jarisplayer, both Open Source).
* Platform preference order selection (e.g. browser, ios, android, flash, native).

'''Cons:'''
* Uses flash where it is not supposed to (e.g. mp4 in Chrome).
* Issues on ios and android (suggests to download file when play button is pressed).
* RTMP only work if defined via playlist rather than in <source> tags.
* Subtitles plugin is not free.

'''Technical notes (lessons learned from the prototypes)'''
* Player initialisation is done using <video> tag directly (no wrapper needed).
* Make sure <video> tag has class attribute with 'projekktor' value (even if you initialise it by ID of the element), player will not work properly otherwise.

'''Missing features'''

=== HTML5 browser native ===

'''Pros:'''
* Simple

'''Cons:'''
* IE8 has no support

'''Technical notes'''
*

'''Missing features'''

== Cross-browser support ==

=== Method ===
Compatibility checks were done manually by accessing the sample page using different browsers and platforms. Sample page contained the list of identical player instances, initialised for each <video> definition with a <source> of particular format: mp4, webm, ogg, flv. Streaming support was checked by setting up a <video> container with two sources of the same video, one was HLS (Apple HTTP Live Streaming) stream for browsers and platforms that support html5 video streaming, another one was RTMP which is played using flash engine and supposed to be used in case if HLS is not supported.

=== Sample Pages ===

* [https://dev.mle.lancs.ac.uk/videotest/players.php?player=flowplayer Flowplayer HTML5] version 5.4.6.
* [https://dev.mle.lancs.ac.uk/videotest/players.php?player=videojs Video.JS] version 4.4.1.
* [https://dev.mle.lancs.ac.uk/videotest/players.php?player=projekktor Projekktor] version 1.3.09.
* [https://dev.mle.lancs.ac.uk/videotest/players.php?player=native Native browser support].

=== Source ===

Source of testing page is hosted on [https://github.com/kabalin/test-html5-players/blob/master/players.php github]. The actual source of the html page can be viewed in browser.

=== Discussion ===

The players comparison that has been carried out demonstrated that "least hassle" player is Flowplayer. Despite some drawbacks listed in [[#Flowplayer_HTML5|corresponding section above]], it is clearly a winner as it works as expected and according to documentation for all browsers and platforms I had chance to test it. This is the only player that supports RTL layout, display platform incompatibility message prior to attempt to play, and was simple to configure (no undocumented tricks that I had to figure out to make it work). Both VideoJS and Projekktor do now perform properly in all cases. Among those two, I personally prefer Projekktor more for its extensive API, plugins infrastructure and configuration flexibility. However problems on mobile platforms and flash fallback inconsistency make them unreliable at this stage.

=== Compatibility results ===

The table was populated using Flowplayer as others do not perform good enough with some formats and platforms, e.g. VideoJS allow mobile platform player to override itself, Projekktor does not always use HTML5 where browser clearly can handle it (supported in native mode and Flowplayer).

{| class="nicetable"
|-
! Browser
! mp4
! webm
! ogg
! flv
! RTMP/HLS*
|-
! Windows 7
| colspan="5"|
|-
!
* Chrome 33.0.1750.117
| html5
| html5
| html5
| flash
| flash
|-
!
* Firefox 27.0.1
| html5
| html5
| html5
| flash
| flash
|-
!
* Opera 12.16
| flash
| html5
| -
| flash
| flash
|-
!
* Safari 5.1.7
| flash
| -
| -
| flash
| flash
|-
!
* Internet Explorer 11.0.9600.x
| html5
| -
| -
| flash
| flash
|-
! Linux (Debian Wheezy)
| colspan="5"|
|-
!
* Chrome 33.0.1750.115
| html5
| html5
| html5
| flash
| flash
|-
! OSX 10.9
| colspan="5"|
|-
!
* Safari 7.0 (9537.71)
| html5
| -
| -
| flash
| html5
|-
!
* Chrome 33.0.1750.117
| html5
| html5
| html5
| flash
| flash
|-
! Android 4.2.2 phone (CyanogenMod, no flash)
| colspan="5"|
|-
!
* Chrome 32.0.1700.99
| html5
| html5
| -
| -
| -
|-
!
* Browser 4.2.2 (com.android.browser)
| html5
| html5
| -
| -
| html5
|-
! Android 4.2.2 tablet (GalaxyTab2, flash app 11.1.115.36)
| colspan="5"|
|-
!
* Chrome 32.0.1700.99
| html5
| html5
| -
| -
| -
|-
!
* Browser 4.2.2 (com.android.browser)
| html5
| html5
| -
| flash
| html5
|-
!
* Opera 19.0.1340.x
| html5
| html5
| -
| -
| -
|-
! iPhone 4S (6.1.3)
| colspan="5"|
|-
!
* Safari
| html5
| -
| -
| -
| html5
|-
! iPad 4 (7.0.6)
| colspan="5"|
|-
!
* Safari
| html5
| -
| -
| -
| html5
|-
|}
* For HLS/RTMP, html5 in the table means HLS has been used, flash means player fell back and used RTMP.

== Sub Tasks ==

In initial stage FlowPlayer HTML5 (or any other) will handle all existing HTML5 Video extensions as per core_media_player_html5video class, plus m3u8 (HLS). It will also be possible optionally to make flash files handled by HTML5 Video player as well (possibility of using existing flash FlowPlayer for flv files will remain).

== Mock-Ups/Prototypes ==

See [[#Sample_Pages|Sample pages]] section.

== Workaround ==

As intermediate solution, if you require player consistency throughout all browsers and platforms, you may consider using JW Player filter: https://github.com/lucisgit/moodle-filter_jwplayer Notice, that JW Player is not free for commercial use.

== Related Tracker Issues ==
* MDL-38158

== Useful links ==
* http://praegnanz.de/html5video/
* http://html5video.org/wiki/HTML5_Video_Player_Comparison
* http://www.streamingmedia.com/Articles/Editorial/Featured-Articles/Choosing-a-Video-Player-Features-and-Specs-for-the-Top-Five-94188.aspx

[[Category:Project]]

Map API

2014-06-27T08:52:40Z

Davidbalch: /* Plugins */ Link to approved plugins.

{{Infobox Project
|name = New Map API
|state = Proposal/Development in progress
|tracker = MDL-42522
|discussion = https://moodle.org/mod/forum/discuss.php?d=245569
}}
{{Moodle 2.7}}This page is for collecting feature requests for a possible new API to enable easy use of geographical maps.

== Current status ==
Moodle + contrib has three separate map implementations:
# The built-in map in the IP address lookup (under /iplookup)
# [https://moodle.org/plugins/view.php?plugin=block_online_users_map block_online_users_map] is a contrib module that shows recent users plotted on a world map.
# [https://moodle.org/plugins/view.php?plugin=block_simple_map block_simple_map] is a contrib module that allows users to search for places specified by a CSV upload

* Additionally, the Database activity has a latlong field, which outputs as links to external mapping services.

== High-level proposal ==

A core module to provide an easy way to add maps and mapping features:
# Display a map with specified size, location, zoom, and tileset.
# Display one or more markers on the map.
# Display popups (or other display methods) with additional information when a user clicks on markers.
# Geocoding (i.e. find lat/long from location name - should adopt existing iplookup solution).
# Input of locations by clicking on the map.
# Reverse geocoding (i.e. find location name from lat/long).

== Existing work (2013-12-10) ==

An alpha level implementation is done, including all proposed features except integration of the existing geocoding system.

=== Map API (local module) ===
* The [http://leafletjs.com/ Leaflet] javascript map library as a YUI module.†
* A PHP class to easily: Add maps, display markers and popups, input locations, perform reverse geocoding.

Demonstration at: http://dbtest.conted.ox.ac.uk/moodlemaps/local/map

† There are other map libs, e.g.:
* OpenLayers - older, larger, with more features than I think we need here.
* Modest Maps - fairly minimal, with fewer
* Polymap - looks interesting for data mapping, but not sure how useful that would be in Moodle.

...however, I'm most familiar with Leaflet and feel it hits the right features/weight balance (e.g. includes geoJSON, but avoids complications with projections), so think it's the right place to start.

=== Database activity submodules ===
# A modification/fork of the latlong field to enable maps for display and input
# A new preset (named "Infomap") to utilise the modified latlong field.

Demonstration at: http://dbtest.conted.ox.ac.uk/moodlemaps/course/view.php?id=2

=== Plugins ===

The local and database modules have been formatted into three modules:
* https://moodle.org/plugins/view.php?plugin=local_map - the API.
* https://moodle.org/plugins/view.php?plugin=datafield_latlongmap - a modified latlong field.
* https://moodle.org/plugins/view.php?plugin=datapreset_infomap_latlongmap - a preset using datafield_latlongmap.

Feedback on the plugins (or the Git branch linked in MDL-42522) would be appreciated.

== Detailed propsal ==
TBC

Events API

2014-05-22T09:33:46Z

Davidbalch: /* Backwards compatibility and migration */ Add link to "Migrating logging calls in plugins" docs

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as capability checks).
; Automatic inclusion
: Event class definitions is automatically included when needed, without having to maintain lists of known event types. New event definitions can be added without the need to upgrade, only purging of the MUC cache is required after adding a new observer.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters has been migrated inside new events method, in get_legacy_log_data(). Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available in 'events.php' files. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Current handlers must not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is separate context cache that may be used when deleting data or for observer performance improvements.
# No database access is allowed in new event dispatching code.
# There is no support for cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Each event class names are a unique identifier of the event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objetid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Old Events API

2014-05-06T09:09:33Z

Davidbalch: Add link to Events 2

'''See [[Event 2]] for the new Events API.'''

==Overview==

The Events API is a core system in Moodle to allow communication between modules.

An '''event''' is when something "interesting" happens in Moodle that is worth alerting the system about.

Any Moodle modules can '''trigger''' new events (with attached data), and other modules can elect to '''handle''' those events with custom functions that operate on the given data.

==Example==

Let's look at an example of how events are used to implement enrolment in Moodle 2.0. In the enrolment system, lib/enrollib.php will generate a 'user_enrolled' event upon completion of an enrolment of a user.

===Triggering an event===

When a user is enrolled, a 'user_enrolled' event is built and sent out by the enrol API. In this example let's pretend someone was just enrolled.

The enrol lib (could even be a module thats creating this event) needs to create an object with the data that this event needs. This may vary completely for different types of events, it's just a data object.
<code php>
$ue = new stdClass();
$ue->enrolid = $instance->id;
$ue->status = is_null($status) ? ENROL_USER_ACTIVE : $status;
$ue->userid = $userid;
$ue->timestart = $timestart;
$ue->timeend = $timeend;
$ue->modifierid = $USER->id;
...
$ue->courseid = $courseid;
$ue->enrol = $name;

events_trigger('user_enrolled', $ue);
</code>
Then we post the object as an event and forget about it:
<code php>
events_trigger('user_enrolled', $eventdata);
</code>
We have now broadcast an event that we think other parts of the system might need to know about.

===Handling an event===

Modules or core code can define an events.php in under its */db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For this case, there is this definition of a handler in mod/forum/db/events.php.

<code php>
$handlers = array (
'user_enrolled' => array (
'handlerfile' => '/mod/forum/lib.php',
'handlerfunction' => 'forum_user_enrolled',
'schedule' => 'instant',
'internal' => 1,
),

'user_unenrolled' => array (
'handlerfile' => '/mod/forum/lib.php',
'handlerfunction' => 'forum_user_unenrolled',
'schedule' => 'instant',
'internal' => 1,
),
);
</code>

These events.php files are parsed during install / upgrade and stored in a simple database table.

Now, when a '''user_enrolled''' event happens, all the registered handlers functions for that event will be called something like this (but with more error handling):
<code php>
include_once($CFG->dirroot.$handlers['user_enrolled']['handlerfile']);
call_user_func($handlers['user_enrolled']['handlerfunction'], $eventdata);
</code>
Any code can hook into any events this way.

The handler function accepts one parameter (the event data object) and should return a boolean. Returning false indicates that there was an error and the event will be left in the event queue.
<code php>
function forum_user_unenrolled($eventdata) {
// handle event
// ...
return true;
}
</code>
note: a lib/db/events.php exists as legacy and no events should be added here. Core API is not supposed to define events for consumption. Only modules and core components (non-api) should define events for consumption/handling.

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handler functions.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'message_send'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /lib/messagelib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

All event names should follow a consistent naming pattern, such as componentname_noun_verb (See [[Frankenstyle]] about the component name)

If the event is being fired after the action has taken place (as in most cases) then use the past tense for the verb (created / deleted / updated / sent).

If the event '''is''' the action, then use the present tense (create / delete / update / send).

==Events which exist==

When we add new events to core we should always add them here too.

Under each event, list the data sent as part of the event.

===Users===
* user_created
** full new record from 'user' table
* user_deleted
** record from 'user' table before marked as deleted
* user_updated
** full new record from 'user' table
* user_enrolled
** full user enrolment record (TBC)
* user_logout
** params TBC
* user_unenrol_modified
** full user enrolment record (TBC)
* user_unenrolled
** full user enrolment record (TBC)

===Roles===
* role_assigned
** full new record from 'role_assignments' table
* role_unassigned
** record from 'role_assignments', course context only

===Courses===
* course_created
** full course record
* course_updated
** full course record
* course_deleted
** full course record
* course_category_deleted
** full category record
* course_content_removed
** full course record
* course_restored (2.5)

===Groups===
* groups_member_added
** groupid, userid
* groups_member_removed
** groupid, userid
* groups_group_created
** id, courseid, name, description, timecreated, timemodified, picture
* groups_group_updated
** id, courseid, name, description, timecreated, timemodified, picture
* groups_group_deleted
** id, courseid, name, description, timecreated, timemodified, picture
* groups_grouping_created
** id, courseid, name, timecreated, timemodified
* groups_grouping_updated
** id, courseid, name, timecreated, timemodified
* groups_grouping_deleted
** id, courseid, name, timecreated, timemodified
* groups_members_removed ''(user deleted from all groups in a course)''
** courseid, userid
* groups_groupings_groups_removed ''(remove all groups from all groupings in a course)''
** courseid (as plain integer, not object)
* groups_groups_deleted ''(delete all groups in a course)''
** courseid (as plain integer, not object)
* groups_groupings_deleted ''(delete all groupings in a course)''
** courseid (as plain integer, not object)

===Cohorts===
* cohort_added
** full cohort record (TBC)
* cohort_deleted
** full cohort record (TBC)
* cohort_member_added
** cohort ID, user ID (TBC)
* cohort_member_removed
** cohort ID, user ID (TBC)
* cohort_updated
** full cohort record (TBC)

===Messaging===
* message_send
** component = 'mod/forum': path in Moodle
** name = 'posts': type of message from that module (as module defines it)
** userfrom = $userfrom: a user object to send from
** userto = $userto: a user object to send to
** subject = 'subject line': a short text line
** fullmessage = 'full plain text': raw text as entered by user
** fullmessageformat = FORMAT_PLAIN|FORMAT_HTML|FORMAT_MOODLE|FORMAT_MARKDOWN: the format of this text
** fullmessagehtml = 'long html text'; html rendered version (optional)
** smallmessage = 'short text': useful for plugins like sms or twitter (optional)

===Portfolio===
* portfolio_send
** id : recordid in portfolio_tempdata table, used for itemid in file storage

===Other===
* assessable_file_uploaded
* assessable_files_done
* mod_created
* mod_deleted
* mod_updated
* quiz_attempt_started
* quiz_attempt_submitted - ''Note: these two quiz events changed in Moodle 2.1''.

==Events wishlist==

List of events which it would be nice to have. Please add to this list if what you want is not shown here.

* mform_print_form -- this for all types of form e.g. admin settings, user profile, module updating, + some sort of standard way of discriminating between them e.g. if ($form->name == 'user_profile') {}. This would be better triggered at the end of the form generation process so that new bits can be inserted at any point, or existing bits could be removed.
* module_installed ''(= mod_created in v2?)''
* module_removed ''(= mod_deleted in v2?)''
* grade_update ''(= quiz_attempt_processed in v2?)''
* assignment_submitted
* course - editing turned on or off
* course completed
* course module completion state changed (completed / not completed)
* course was reset
* Some will_be ... events that would allow another plugin to react before these things happen:
** course_will_be_restored (with info about course being restored and the target category)
** course_category_will_be_moved (with info about category being moved and target category)
** course_will_be_moved (with course info and target category info)

Provide event trigger hooks for the modules, similar to what is done for the cron service which checks the LOCAL directory for a cron file. It is already possible to define an event trigger but the core/module code must be modified to actually make use of it.

== See also ==

* [[Core APIs]]
* [http://moodle.org/mod/forum/discuss.php?d=69103 Original General Developer Forum thread discussing this proposal].
* [[Messaging_2.0]]
* [[Event_2]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]
[[Category:API]]

Assign submission plugins

2014-05-02T14:34:18Z

Davidbalch: /* locallib.php */ Add headings for assign_submission_plugin functions, to improve readability.

== Introduction ==
This page gives an overview of assignment submission plugims within the assignment module.

=== Overview of an assignment submission plugin ===
An assignment submission plugin is used to display custom form fields to a student when they are editing their assignment submission. It also has full control over the display the submitted assignment to graders and students. Plugins participate in all assignment features including backup/restore, upgrades from 2.2, offline grading, group assignments and blind marking.
<gallery>
File:assignsubmission_plugin_overview1.png|An assignment submission plugin can add settings to the module settings page.
File:assignsubmission_plugin_overview2.png|An assignment submission plugin can show a summary of the submission to students and graders.
File:assignsubmission_plugin_overview3.png|An assignment submission plugin can add form fields to the student submission page.
</gallery>

== History ==
Assignment submission plugins were added with the assignment module rewrite for Moodle 2.3.

== Template ==
A great example is the "onlinetext" submission plugin included with Moodle core.

== File structure ==
The files for a custom submission plugin sit under "mod/assign/submission/<pluginname>". A plugin should not include any custom files outside of it's own plugin folder.

Note: The plugin name should be no longer than 11 characters - this is because the database tables for a submission plugin must be prefixed with "assignsubmission_" + pluginname (17 chars + X) and the table names can be no longer than 28 chars (thanks oracle). If a plugin requires multiple database tables, the plugin name will need to be shorter to allow different table names to fit under the 28 character limit.

All examples in this document exclude the required copyright and license information from source files for brevity.

=== version.php ===

To start with we need to tell Moodle the version information for our new plugin so that it can be installed and upgraded correctly. This information is added to version.php as with any other type of Moodle plugin. The component name must begin with "assignsubmission_" to identify this as a submission plugin.

See [[version.php]] for more information.
<pre>
defined('MOODLE_INTERNAL') || die();

$plugin->version = 2012112900;
$plugin->requires = 2012112900;
$plugin->component = 'assignsubmission_file';
</pre>

=== settings.php ===

The settings file allows us to add custom settings to the system wide configuration page for our plugin.

All submission settings should be named 'assignsubmission_pluginname/settingname' in order for the setting to be associated with the plugin.

All submission plugins should include one setting named 'default' to indicate if the plugin should be enabled by default when creating a new assignment.

This example from the submission_file plugin also checks to see if there is a maxbytes setting for this moodle installation and if found, it adds a new admin setting to the settings page. The name of the setting should begin with the plugin component name ("assignsubmission_file") in this case. The strings are specified in this plugins language file.

<pre>
// Note: This is on by default.
$settings->add(new admin_setting_configcheckbox('assignsubmission_file/default',
new lang_string('default', 'assignsubmission_file'),
new lang_string('default_help', 'assignsubmission_file'), 1));

if (isset($CFG->maxbytes)) {

$name = new lang_string('maximumsubmissionsize', 'assignsubmission_file');
$description = new lang_string('configmaxbytes', 'assignsubmission_file');

$element = new admin_setting_configselect('assignsubmission_file/maxbytes',
$name,
$description,
1048576,
get_max_upload_sizes($CFG->maxbytes));
$settings->add($element);
}
</pre>

=== lang/en/submission_pluginname.php ===

The language file for this plugin must have the same name as the component name (e.g. "submission_file.php"). It should at least define a string for "pluginname". For example:

<pre>
$string['pluginname'] = 'Awesome submissions';
</pre>

=== db/access.php ===

This is where any additional capabilities are defined if required. This file can be omitted if there are no capabilities added by the plugin.

See [[Activity_modules#access.php]] for more information.
<pre>
$capabilities = array(
'assignsubmission/dungeon:master' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</pre>

=== db/upgrade.php ===

This is where any upgrade code is defined.

See [[Activity_modules#upgrade.php]] for more infomation.
<pre>
function xmldb_submission_file_upgrade($oldversion) {
global $CFG, $DB, $OUTPUT;

$dbman = $DB->get_manager();
if ($oldversion < 2012091800) {
// Put upgrade code here

// Savepoint reached.
upgrade_plugin_savepoint(true, 2012091800, 'assignsubmission', 'file');
}

return true;
}

</pre>

=== db/install.xml ===

This is where any database tables required to save this plugins data are defined. File submissions define a table that links to submission and contains a column to record the number of files.

<pre>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/assign/submission/file/db" VERSION="20120423" COMMENT="XMLDB file for Moodle mod/assign/submission/file"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="assignsubmission_file" COMMENT="Info about file submissions for assignments">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="true"/>
<FIELD NAME="assignment" TYPE="int" LENGTH="10" NOTNULL="true" DEFAULT="0" SEQUENCE="false"/>
<FIELD NAME="submission" TYPE="int" LENGTH="10" NOTNULL="true" DEFAULT="0" SEQUENCE="false"/>
<FIELD NAME="numfiles" TYPE="int" LENGTH="10" NOTNULL="true" DEFAULT="0" SEQUENCE="false" COMMENT="The number of files the student submitted."/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="The unique id for this submission info."/>
<KEY NAME="assignment" TYPE="foreign" FIELDS="assignment" REFTABLE="assign" REFFIELDS="id" COMMENT="The assignment instance this submission relates to"/>
<KEY NAME="submission" TYPE="foreign" FIELDS="submission" REFTABLE="assign_submission" REFFIELDS="id" COMMENT="The submission this file submission relates to."/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</pre>

=== db/install.php ===

This example is from the submission_comments plugin. It shows how to run custom code on installation of the plugin. In this case it makes the comments plugin the last of the three submission plugins installed by default.

<pre>
/**
* Code run after the plugin database tables have been created.
*/
function xmldb_submission_comments_install() {
global $CFG, $DB, $OUTPUT;

// do the install

require_once($CFG->dirroot . '/mod/assign/locallib.php');
// set the correct initial order for the plugins
$assignment = new assignment();
$plugin = $assignment->get_submission_plugin_by_type('comments');
if ($plugin) {
$plugin->move('down');
$plugin->move('down');
}

return true;
}

</pre>

=== locallib.php ===

This is where all the functionality for this plugin is defined. We will step through this file and describe each part as we go.

<pre>

class assign_submission_file extends assign_submission_plugin {

</pre>

All submission plugins MUST define a class with the component name of the plugin that extends assign_submission_plugin.

==== ''' get_name()''' ====
<pre>

public function get_name() {
return get_string('file', 'assignsubmission_file');
}

</pre>

Get name is abstract in submission_plugin and must be defined in your new plugin. Use the language strings to make your plugin translatable.

==== ''' get_settings()''' ====
<pre>
public function get_settings(MoodleQuickForm $mform) {
global $CFG, $COURSE;

$defaultmaxfilesubmissions = $this->get_config('maxfilesubmissions');
$defaultmaxsubmissionsizebytes = $this->get_config('maxsubmissionsizebytes');

$settings = array();
$options = array();
for ($i = 1; $i <= ASSIGNSUBMISSION_FILE_MAXFILES; $i++) {
$options[$i] = $i;
}

$name = get_string('maxfilessubmission', 'assignsubmission_file');
$mform->addElement('select', 'assignsubmission_file_maxfiles', $name, $options);
$mform->addHelpButton('assignsubmission_file_maxfiles',
'maxfilessubmission',
'assignsubmission_file');
$mform->setDefault('assignsubmission_file_maxfiles', $defaultmaxfilesubmissions);
$mform->disabledIf('assignsubmission_file_maxfiles', 'assignsubmission_file_enabled', 'notchecked');

$choices = get_max_upload_sizes($CFG->maxbytes,
$COURSE->maxbytes,
get_config('assignsubmission_file', 'maxbytes'));

$settings[] = array('type' => 'select',
'name' => 'maxsubmissionsizebytes',
'description' => get_string('maximumsubmissionsize', 'assignsubmission_file'),
'options'=> $choices,
'default'=> $defaultmaxsubmissionsizebytes);

$name = get_string('maximumsubmissionsize', 'assignsubmission_file');
$mform->addElement('select', 'assignsubmission_file_maxsizebytes', $name, $choices);
$mform->addHelpButton('assignsubmission_file_maxsizebytes',
'maximumsubmissionsize',
'assignsubmission_file');
$mform->setDefault('assignsubmission_file_maxsizebytes', $defaultmaxsubmissionsizebytes);
$mform->disabledIf('assignsubmission_file_maxsizebytes',
'assignsubmission_file_enabled',
'notchecked');
}
</pre>

The "get_settings" function is called when building the settings page for the assignment. It allows this plugin to add a list of settings to the form. Notice that the settings are prefixed by the plugin name which is good practice to avoid conflicts with other plugins.

==== ''' save_settings()''' ====
<pre>
public function save_settings(stdClass $data) {
$this->set_config('maxfilesubmissions', $data->assignsubmission_file_maxfiles);
$this->set_config('maxsubmissionsizebytes', $data->assignsubmission_file_maxsizebytes);
return true;
}
</pre>

The "save_settings" function is called when the assignment settings page is submitted, either for a new assignment or when editing an existing one. For settings specific to a single instance of the assignment you can use the assign_plugin::set_config function shown here to save key/value pairs against this assignment instance for this plugin.

==== ''' get_form_elements()''' ====
<pre>
public function get_form_elements($submission, MoodleQuickForm $mform, stdClass $data) {

if ($this->get_config('maxfilesubmissions') <= 0) {
return false;
}

$fileoptions = $this->get_file_options();
$submissionid = $submission ? $submission->id : 0;

$data = file_prepare_standard_filemanager($data,
'files',
$fileoptions,
$this->assignment->get_context(),
'assignsubmission_file',
ASSIGNSUBMISSION_FILE_FILEAREA,
$submissionid);
$mform->addElement('filemanager', 'files_filemanager', html_writer::tag('span', $this->get_name(),
array('class' => 'accesshide')), null, $fileoptions);

return true;
}

</pre>

The get_form_elements function is called when building the submission form. It functions identically to the get_settings function except that the submission object is available (if there is a submission) to associate the settings with a single submission. This example also shows how to use a filemanager within a submission plugin. The function must return true if it has modified the form otherwise the assignment will not include a header for this plugin.

==== ''' save()''' ====
<pre>
public function save(stdClass $submission, stdClass $data) {
global $USER, $DB;

$fileoptions = $this->get_file_options();

$data = file_postupdate_standard_filemanager($data,
'files',
$fileoptions,
$this->assignment->get_context(),
'assignsubmission_file',
ASSIGNSUBMISSION_FILE_FILEAREA,
$submission->id);

$filesubmission = $this->get_file_submission($submission->id);

// Plagiarism code event trigger when files are uploaded.

$fs = get_file_storage();
$files = $fs->get_area_files($this->assignment->get_context()->id,
'assignsubmission_file',
ASSIGNSUBMISSION_FILE_FILEAREA,
$submission->id,
'id',
false);

$count = $this->count_files($submission->id, ASSIGNSUBMISSION_FILE_FILEAREA);

// Send files to event system.
// This lets Moodle know that an assessable file was uploaded (eg for plagiarism detection).
$eventdata = new stdClass();
$eventdata->modulename = 'assign';
$eventdata->cmid = $this->assignment->get_course_module()->id;
$eventdata->itemid = $submission->id;
$eventdata->courseid = $this->assignment->get_course()->id;
$eventdata->userid = $USER->id;
if ($count > 1) {
$eventdata->files = $files;
}
$eventdata->file = $files;
$eventdata->pathnamehashes = array_keys($files);
events_trigger('assessable_file_uploaded', $eventdata);

if ($filesubmission) {
$filesubmission->numfiles = $this->count_files($submission->id,
ASSIGNSUBMISSION_FILE_FILEAREA);
return $DB->update_record('assignsubmission_file', $filesubmission);
} else {
$filesubmission = new stdClass();
$filesubmission->numfiles = $this->count_files($submission->id,
ASSIGNSUBMISSION_FILE_FILEAREA);
$filesubmission->submission = $submission->id;
$filesubmission->assignment = $this->assignment->get_instance()->id;
return $DB->insert_record('assignsubmission_file', $filesubmission) > 0;
}
</pre>

The "save" function is called to save a user submission. The parameters are the submission object and the data from the submission form. This example calls file_postupdate_standard_filemanager to copy the files from the draft file area to the filearea for this submission, it then uses the event api to trigger an assessable_file_uploaded event for the plagiarism api. It then records the number of files in the plugin specific "assignsubmission_file" table.

==== ''' get_files()''' ====
<pre>
public function get_files($submission) {
$result = array();
$fs = get_file_storage();

$files = $fs->get_area_files($this->assignment->get_context()->id,
'assignsubmission_file',
ASSIGNSUBMISSION_FILE_FILEAREA,
$submission->id,
'timemodified',
false);

foreach ($files as $file) {
$result[$file->get_filename()] = $file;
}
return $result;
}

</pre>

If this submission plugin produces one or more files, it should implement "get_files" so that the portfolio API can export a list of all the files from all of the plugins for this assignment submission. This is also used by the offline grading feature in the assignment.

==== ''' view_summary()''' ====
<pre>
public function view_summary(stdClass $submission, & $showviewlink) {
$count = $this->count_files($submission->id, ASSIGNSUBMISSION_FILE_FILEAREA);

// Show we show a link to view all files for this plugin?
$showviewlink = $count > ASSIGNSUBMISSION_FILE_MAXSUMMARYFILES;
if ($count <= ASSIGNSUBMISSION_FILE_MAXSUMMARYFILES) {
return $this->assignment->render_area_files('assignsubmission_file',
ASSIGNSUBMISSION_FILE_FILEAREA,
$submission->id);
} else {
return get_string('countfiles', 'assignsubmission_file', $count);
}
}
</pre>

The view_summary function is called to display a summary of the submission to both markers and students. It counts the number of files submitted and if it is more that a set number, it only displays a count of how many files are in the submission - otherwise it uses a helper function to write the entire list of files. This is because we want to keep the summaries really short so they can be displayed in a table. There will be a link to view the full submission on the submission status page.

==== ''' view()''' ====
<pre>
public function view($submission) {
return $this->assignment->render_area_files('assignsubmission_file',
ASSIGNSUBMISSION_FILE_FILEAREA,
$submission->id);
}
</pre>

The view function is called to display the entire submission to both markers and students. In this case it uses the helper function in the assignment class to write the list of files.

==== ''' can_upgrade()''' ====
<pre>
public function can_upgrade($type, $version) {

$uploadsingle_type ='uploadsingle';
$upload_type ='upload';

if (($type == $uploadsingle_type || $type == $upload_type) && $version >= 2011112900) {
return true;
}
return false;
}

</pre>

The can_upgrade function is used to identify old "Assignment 2.2" subtypes that can be upgraded by this plugin. This plugin supports upgrades from the old "upload" and "uploadsingle" assignment subtypes.

==== ''' upgrade_settings()''' ====
<pre>

public function upgrade_settings(context $oldcontext, stdClass $oldassignment, & $log) {
global $DB;

if ($oldassignment->assignmenttype == 'uploadsingle') {
$this->set_config('maxfilesubmissions', 1);
$this->set_config('maxsubmissionsizebytes', $oldassignment->maxbytes);
return true;
} else if ($oldassignment->assignmenttype == 'upload') {
$this->set_config('maxfilesubmissions', $oldassignment->var1);
$this->set_config('maxsubmissionsizebytes', $oldassignment->maxbytes);

// Advanced file upload uses a different setting to do the same thing.
$DB->set_field('assign',
'submissiondrafts',
$oldassignment->var4,
array('id'=>$this->assignment->get_instance()->id));

// Convert advanced file upload "hide description before due date" setting.
$alwaysshow = 0;
if (!$oldassignment->var3) {
$alwaysshow = 1;
}
$DB->set_field('assign',
'alwaysshowdescription',
$alwaysshow,
array('id'=>$this->assignment->get_instance()->id));
return true;
}
}

</pre>

This function is called once per assignment instance to upgrade the settings from the old assignment to the new mod_assign. In this case it sets the maxbytes, maxfiles and alwaysshowdescription configuration settings.

==== ''' upgrade()''' ====
<pre>

public function upgrade($oldcontext,$oldassignment, $oldsubmission, $submission, & $log) {
global $DB;

$file_submission = new stdClass();

$file_submission->numfiles = $oldsubmission->numfiles;
$file_submission->submission = $submission->id;
$file_submission->assignment = $this->assignment->get_instance()->id;

if (!$DB->insert_record('assign_submission_file', $file_submission) > 0) {
$log .= get_string('couldnotconvertsubmission', 'mod_assign', $submission->userid);
return false;
}

// now copy the area files
$this->assignment->copy_area_files_for_upgrade($oldcontext->id,
'mod_assignment',
'submission',
$oldsubmission->id,
// New file area
$this->assignment->get_context()->id,
'mod_assign',
ASSIGN_FILEAREA_SUBMISSION_FILES,
$submission->id);

return true;
}
</pre>

The "upgrade" function upgrades a single submission from the old assignment type to the new one. In this case it involves copying all the files from the old filearea to the new one. There is a helper function available in the assignment class for this (Note: the copy will be fast as it is just adding rows to the files table). If this function returns false, the upgrade will be aborted and rolled back.

==== ''' get_editor_fields()''' ====
<pre> public function () {
return array('onlinetext' => get_string('pluginname', 'assignsubmission_comments'));
}
</pre>

This example is from assignsubmission_onlinetext. If the plugin uses a text-editor it is ideal if the plugin implements "get_editor_fields". This allows the portfolio to retrieve the text from the plugin when exporting the list of files for a submission. This is required because the text is stored in the plugin specific table that is only known to the plugin itself. If a plugin supports multiple text areas it can return the name of each of them here.

==== ''' get_editor_text()''' ====
<pre>
public function get_editor_text($name, $submissionid) {
if ($name == 'onlinetext') {
$onlinetextsubmission = $this->get_onlinetext_submission($submissionid);
if ($onlinetextsubmission) {
return $onlinetextsubmission->onlinetext;
}
}

return '';
}
</pre>

This example is from assignsubmission_onlinetext. If the plugin uses a text-editor it is ideal if the plugin implements "get_editor_text". This allows the portfolio to retrieve the text from the plugin when exporting the list of files for a submission. This is required because the text is stored in the plugin specific table that is only known to the plugin itself. The name is used to distinguish between multiple text areas in the one plugin.

==== ''' get_editor_format()''' ====
<pre>
public function get_editor_format($name, $submissionid) {
if ($name == 'onlinetext') {
$onlinetext_submission = $this->get_onlinetext_submission($submissionid);
if ($onlinetext_submission) {
return $onlinetext_submission->onlineformat;
}
}

return 0;
}
</pre>

This example is from assignsubmission_onlinetext. For the same reason as the previous function, if the plugin uses a text editor, it is ideal if the plugin implements "get_editor_format". This allows the portfolio to retrieve the text from the plugin when exporting the list of files for a submission. This is required because the text is stored in the plugin specific table that is only known to the plugin itself. The name is used to distinguish between multiple text areas in the one plugin.

==== ''' is_empty()''' ====
<pre>
public function is_empty(stdClass $submission) {
return $this->count_files($submission->id, ASSIGNSUBMISSION_FILE_FILEAREA) == 0;
}
</pre>

If a plugin has no submission data to show - it can return true from the is_empty function. This prevents a table row being added to the submission summary for this plugin. It is also used to check if a student has tried to save an assignment with no data.

==== ''' get_file_areas()''' ====
<pre>
public function get_file_areas() {
return array(ASSIGNSUBMISSION_FILE_FILEAREA=>$this->get_name());
}
</pre>

A plugin should implement get_file_areas if it supports saving of any files to moodle - this allows the file areas to be browsed by the moodle file manager.

==== ''' copy_submission()''' ====
<pre>
public function copy_submission(stdClass $sourcesubmission, stdClass $destsubmission) {
global $DB;

// Copy the files across.
$contextid = $this->assignment->get_context()->id;
$fs = get_file_storage();
$files = $fs->get_area_files($contextid,
'assignsubmission_file',
ASSIGNSUBMISSION_FILE_FILEAREA,
$sourcesubmission->id,
'id',
false);
foreach ($files as $file) {
$fieldupdates = array('itemid' => $destsubmission->id);
$fs->create_file_from_storedfile($fieldupdates, $file);
}

// Copy the assignsubmission_file record.
if ($filesubmission = $this->get_file_submission($sourcesubmission->id)) {
unset($filesubmission->id);
$filesubmission->submission = $destsubmission->id;
$DB->insert_record('assignsubmission_file', $filesubmission);
}
return true;
}
</pre>

Since Moodle 2.5 - a students submission can be copied to create a new submission attempt. Plugins should implement this function if they store data associated with the submission (most plugins).

==== ''' format_for_log()''' ====
<pre>
public function (stdClass $submission) {
// format the info for each submission plugin add_to_log
$filecount = $this->count_files($submission->id, ASSIGNSUBMISSION_FILE_FILEAREA);
$fileloginfo = '';
$fileloginfo .= ' the number of file(s) : ' . $filecount . " file(s). ";

return $fileloginfo;
}
</pre>

The format_for_log function lets a plugin produce a really short summary of a submission suitable for adding to a log message.

==== ''' delete_instance()''' ====
<pre>
public function delete_instance() {
global $DB;
// will throw exception on failure
$DB->delete_records('assignsubmission_file', array('assignment'=>$this->assignment->get_instance()->id));

return true;
}
</pre>

The delete_instance function is called when a plugin is deleted. Note only database records need to be cleaned up - files belonging to fileareas for this assignment will be automatically cleaned up.

=== lib.php ===

This file is the entry point to many standard Moodle APIs for plugins. An example is that in order for a plugin to allow users to download files contained within a filearea belonging to the plugin, they must implement the componentname_pluginfile function in order to perform their own security checks.

See [[File_API]] for more information.
Example:
<pre>
function assignfeedback_file_pluginfile($course,
$cm,
context $context,
$filearea,
$args,
$forcedownload) {
global $USER, $DB;

if ($context->contextlevel != CONTEXT_MODULE) {
return false;
}

require_login($course, false, $cm);
$itemid = (int)array_shift($args);
$record = $DB->get_record('assign_grades', array('id'=>$itemid), 'userid,assignment', MUST_EXIST);
$userid = $record->userid;

if (!$assign = $DB->get_record('assign', array('id'=>$cm->instance))) {
return false;
}

if ($assign->id != $record->assignment) {
return false;
}

// Check is users feedback or has grading permission.
if ($USER->id != $userid and !has_capability('mod/assign:grade', $context)) {
return false;
}

$relativepath = implode('/', $args);

$fullpath = "/{$context->id}/assignfeedback_file/$filearea/$itemid/$relativepath";

$fs = get_file_storage();
if (!$file = $fs->get_file_by_hash(sha1($fullpath)) or $file->is_directory()) {
return false;
}
// Download MUST be forced - security!
send_stored_file($file, 0, 0, true);
}
</pre>

== Useful classes ==
A submission plugin has access to a number of useful classes in the assignment module. See the phpdocs (or the code) for more information on these classes.

=== assign_plugin ===
This abstract class is the base class for all assignment plugins (feedback or submission plugins).

It provides access to the assign class which represents the current assignment instance through "$this->assignment".

=== assign_submission_plugin ===
This is the base class all assignment submission plugins must extend. It contains a small number of additional function that only apply to submission plugins.

=== assign ===
This is the main class for interacting with the assignment module.

It contains public functions that are useful for listing users, loading and updating submissions, loading and updating grades, displaying users etc.

Map API

2013-12-16T16:13:53Z

Davidbalch:

{{Infobox Project
|name = New Map API
|state = Proposal/Development in progress
|tracker = MDL-42522
|discussion = https://moodle.org/mod/forum/discuss.php?d=245569
}}
{{Moodle 2.7}}This page is for collecting feature requests for a possible new API to enable easy use of geographical maps.

== Current status ==
Moodle + contrib has three separate map implementations:
# The built-in map in the IP address lookup (under /iplookup)
# [https://moodle.org/plugins/view.php?plugin=block_online_users_map block_online_users_map] is a contrib module that shows recent users plotted on a world map.
# [https://moodle.org/plugins/view.php?plugin=block_simple_map block_simple_map] is a contrib module that allows users to search for places specified by a CSV upload

* Additionally, the Database activity has a latlong field, which outputs as links to external mapping services.

== High-level proposal ==

A core module to provide an easy way to add maps and mapping features:
# Display a map with specified size, location, zoom, and tileset.
# Display one or more markers on the map.
# Display popups (or other display methods) with additional information when a user clicks on markers.
# Geocoding (i.e. find lat/long from location name - should adopt existing iplookup solution).
# Input of locations by clicking on the map.
# Reverse geocoding (i.e. find location name from lat/long).

== Existing work (2013-12-10) ==

An alpha level implementation is done, including all proposed features except integration of the existing geocoding system.

=== Map API (local module) ===
* The [http://leafletjs.com/ Leaflet] javascript map library as a YUI module.†
* A PHP class to easily: Add maps, display markers and popups, input locations, perform reverse geocoding.

Demonstration at: http://dbtest.conted.ox.ac.uk/moodlemaps/local/map

† There are other map libs, e.g.:
* OpenLayers - older, larger, with more features than I think we need here.
* Modest Maps - fairly minimal, with fewer
* Polymap - looks interesting for data mapping, but not sure how useful that would be in Moodle.

...however, I'm most familiar with Leaflet and feel it hits the right features/weight balance (e.g. includes geoJSON, but avoids complications with projections), so think it's the right place to start.

=== Database activity submodules ===
# A modification/fork of the latlong field to enable maps for display and input
# A new preset (named "Infomap") to utilise the modified latlong field.

Demonstration at: http://dbtest.conted.ox.ac.uk/moodlemaps/course/view.php?id=2

=== Plugins ===

The local and database modules have been formatted into three modules, awaiting approval:
* local_map - the API.
* datafield_latlongmap - a modified latlong field.
* datapreset_infomap_latlongmap - a preset using datafield_latlongmap.

== Detailed propsal ==
TBC

Map API

2013-12-10T16:16:27Z

Davidbalch: First draft

{{Infobox Project
|name = New Map API
|state = Proposal/Development in progress
|tracker = MDL-42522
}}
{{Moodle 2.7}}This page is for collecting feature requests for a possible new API to enable easy use of geographical maps.

== Current status ==
Moodle + contrib has three separate map implementations:
# The built-in map in the IP address lookup (under /iplookup)
# [https://moodle.org/plugins/view.php?plugin=block_online_users_map block_online_users_map] is a contrib module that shows recent users plotted on a world map.
# [https://moodle.org/plugins/view.php?plugin=block_simple_map block_simple_map] is a contrib module that allows users to search for places specified by a CSV upload

* Additionally, the Database activity has a latlong field, which outputs as links to external mapping services.

== High-level proposal ==

A core module to provide an easy way to add maps and mapping features:
# Display a map with specified size, location, zoom, and tileset.
# Display one or more markers on the map.
# Display popups (or other display methods) with additional information when a user clicks on markers.
# Geocoding (i.e. find lat/long from location name - should adopt existing iplookup solution).
# Input of locations by clicking on the map.
# Reverse geocoding (i.e. find location name from lat/long).

== Existing work (2013-12-10) ==

An alpha level implementation is done, including all proposed features except integration of the existing geocoding system.

=== Map API (local module) ===
* The [http://leafletjs.com/ Leaflet] javascript map library as a YUI module.†
* A PHP class to easily: Add maps, display markers and popups, input locations, perform reverse geocoding.

Demonstration at: http://dbtest.conted.ox.ac.uk/moodlemaps/local/map

† There are other map libs, e.g.:
* OpenLayers - older, larger, with more features than I think we need here.
* Modest Maps - fairly minimal, with fewer
* Polymap - looks interesting for data mapping, but not sure how useful that would be in Moodle.

...however, I'm most familiar with Leaflet and feel it hits the right features/weight balance (e.g. includes geoJSON, but avoids complications with projections), so think it's the right place to start.

=== Database activity submodules ===
# A modification/fork of the latlong field to enable maps for display and input
# A new preset (named "Infomap") to utilise the modified latlong field.

Demonstration at: http://dbtest.conted.ox.ac.uk/moodlemaps/course/view.php?id=2

=== Plugins ===

The local and database modules have been formatted into three modules, awaiting approval:
* local_map - the API.
* datafield_latlongmap - a modified latlong field.
* datapreset_infomap_latlongmap - a preset using datafield_latlongmap.

== Detailed propsal ==
TBC

Using the File API in Moodle forms

2012-06-28T16:15:29Z

Davidbalch: /* Add file manager element */ Update accepted_types info.

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[File API|File API]], and every file is associated with a component and a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the [[Repository API|Repository API]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[File API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null,
array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>

==== Obtain the chosen file ====

The API for getting file contents is exactly the same as for ''file'' element.

<code php>
$content = $mform->get_file_content('userfile');
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50,
'accepted_types' => array('document') ));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 1) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;accepted_types:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/filestorage/file_types.mm moodle/lib/filestorage/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle.

As of 2.3 file_types.mm is no longer used, instead the file types are listed in <code>get_mimetypes_array()</code> in filelib.php (https://github.com/moodle/moodle/blob/master/lib/filelib.php#L1360).

Example usage: '''array('audio', 'video', 'documents')''', you can include file extensions as well, for example: '''array('*.txt', '*.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new stdClass;
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');

file_prepare_draft_area($draftitemid, $context->id, 'mod_glossary', 'attachment', $entry->id,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));

$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'mod_glossary', 'attachment',
$entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two ways of using the editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array. note that context is the best, most local context you have available. <code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles,
'maxbytes'=>$maxbytes, 'context'=>$context);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet <code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'),
null, $textfieldoptions);</code>
# prepare data <code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context,
'mod_somemodule', 'somearea', $data->id);</code>
# get submitted data and after inserting/updating of data <code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context,
'mod_somemodule', 'somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_mymodule', 'proper_file_area', $itemid);
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; $context->id, 'mod_mymodule', 'proper_file_area', $itemid : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes;
// Could also use $CFG->maxbytes if you are not coding within a course context

$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true,
'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'),
array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0,
true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'),
'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null,
$definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'),
null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2',
get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly
* Make sure $definitionoptions has context parameter, else system context is used and editor will not respect filter settings.

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

=== Gotchas ===
A few things to keep in mind:
* Make sure that you instantiate the moodle form before any call to $OUTPUT->header()

== See also ==

* [[File API]]
* [[Using the file API]]
* [[Repository API]]
* [[Portfolio API]]
* MDL-14589 - File API Meta issue

[[Category:Files]]
[[Category:Repositories]]

Filters schema

2007-05-04T08:37:21Z

Davidbalch:

The objective of this page is to document all the ideas and improvements to be implemented in the "Filters" functionality of Moodle.

Every idea will be documented here, including its associated "thoughts" and potential "implementations". Feel free to add/modify everything as you want!

These are the main areas to discuss/analyse/implement:

* [[Course/site filters | Enable/Disable Filters by Course and Site]]
* [[Course/site filter config | Optional Configuration of Filters by Course and Site]]
* [[Multilang filter | Changes in the Caching System to Support the Multilang Filter]]
* [[Enable/Disable Filters by Activities]]
* Allow filtering data before it will save in database? It will do possible exclude some data from text (like TeX formulas) and save in separate table. It will allow change formula by clicking on it and open popup window.
* It'd be great if you could set the text cache lifetime for individual filters. This would be handy for filters that use external resources (e.g., Wikipedia) that sometimes have slow response times. I'd guess that you could use a cache lifetime of a week or more for a Wikipedia filter without causing major usability problems.

==See also==

*[http://moodle.org/bugs/bug.php?op=show&bugid=2400 Bug 2400] - a lot of ideas and request have been written here
http://tracker.moodle.org/browse/MDL-9443 - add support for filtering XHTML resources as well as HTML.

Course/site filter config

2007-04-18T10:37:14Z

Davidbalch: Added config idea.

This topic is to define how to add the possibility of "configure" filters both at site and course level.

* The mp3player may be configured at site level to only start downloading when the play button is pressed.
* The filters could configured to apply to classes of files by MIME type and/or file extension.