A heading can be added
"); + } +} + +// fixtures/core_renderer/before_standard_footer_html_hooks.php +$callbacks = [ + [ + 'hook' => \core\hook\output\before_standard_footer_html::class, + 'callback' => [ + \test_fixtures\core_renderer\before_standard_footer_html_callbacks::class, + 'before_standard_footer_html', + ], + ], +]; +``` + +:::note + +Prior to Moodle 4.3 the only way to dispatch a hook is by accessing the manager instance: + +```php +\core\hook\manager::get_instance()->dispatch($hook); +``` + +This approach is harder to test in situ. + +::: + +## Registering of hook callbacks + +Any plugin is free to register callbacks for all core and plugin hooks. +The registration is done by adding a `db/hooks.php` file to plugin. +Callbacks may be provided as a PHP callable in either: + +- string notation, in the form of `some\class\name::static_method`; or +- array notation, in the form of `[\some\class\name::class, 'static_method']`. + +:::danger Use of array notation + +anonymous
+html_writer::div('kermit', 'frog'); // kermit
+```
+
+Attributes can be set by an array with key-value pairs.
+
+```php
+html_writer::div('Mr', 'toad', array('id' => 'tophat'));
+// Mr/div>
+```
+
+### span
+
+```php
+html_writer::start_span('zombie') . 'BRAINS' . html_writer::end_span();
+// BRAINS
+```
+
+### Generic tags
+
+```php
+html_writer::tag(tag_name, contents, attributes=null);
+html_writer::start_tag(tag_name, attributes=null;);
+html_writer::end_tag(tag_name);
+html_writer::empty_tag(tag_name, attributes=null);
+html_writer::nonempty_tag(tag_name, content, attributes=null);
+html_writer::attribute(name, value);
+html_writer::attributes(attributes_array);
+```
diff --git a/versioned_docs/version-5.1/apis/core/index.md b/versioned_docs/version-5.1/apis/core/index.md
new file mode 100644
index 0000000000..68027faa93
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/core/index.md
@@ -0,0 +1,8 @@
+---
+title: Core APIs
+tags:
+ - core
+ - API
+---
+
+Moodle provides a series of Core APIs which can be used by any part of Moodle.
diff --git a/versioned_docs/version-5.1/apis/core/lock/index.md b/versioned_docs/version-5.1/apis/core/lock/index.md
new file mode 100644
index 0000000000..7b80a348f2
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/core/lock/index.md
@@ -0,0 +1,73 @@
+---
+title: Lock API
+tags:
+ - API
+ - Lock
+---
+
+Locking is required whenever you need to prevent two, or more, processes accessing the same resource at the same time. The prime candidate for locking in Moodle is cron. Locking allows multiple cron processes to work on different parts of cron at the same time with no risk that they will conflict (work on the same job at the same time).
+
+## When to use locking
+
+When you want to prevent multiple requests from accessing the same resource at the same time. Accessing a resource is a vague description, but it could be for example running a slow running task in the background, running different parts of cron etc.
+
+## Performance
+
+Locking is not meant to be fast. Do not use it in code that will be triggered many times in a single request (for example MUC). It is meant to be always correct - even for multiple nodes in a cluster. This implies that the locks are communicated among all the nodes in the cluster, and hence it will never be super quick.
+
+## Usage
+
+The locking API is used by getting an instance of a lock_factory, and then using it to retrieve locks, and eventually releasing them. You are required to release all your locks, even on the event of failures.
+
+```php
+$timeout = 5;
+
+// A namespace for the locks. Must be prefixed with the component name to prevent conflicts.
+$locktype = 'mod_assign_download_submissions';
+
+// Resource key - needs to uniquely identify the resource that is to be locked. E.g. If you
+// want to prevent a user from running multiple course backups - include the userid in the key.
+$resource = 'user:' . $USER->id;
+
+// Get an instance of the currently configured lock_factory.
+$lockfactory = \core\lock\lock_config::get_lock_factory($locktype);
+
+// Get a new lock for the resource, wait for it if needed.
+if ($lock = $lockfactory->get_lock($resource, $timeout)) {
+ // We have exclusive access to the resource, do the slow zip file generation...
+
+ if ($someerror) {
+ // Always release locks on failure.
+ $lock->release();
+ print_error('blah');
+ }
+
+ // Release the lock once finished.
+ $lock->release();
+
+} else {
+ // We did not get access to the resource in time, give up.
+ throw new moodle_exception('locktimeout');
+}
+```
+
+## Use a different lock type from the default
+
+Change the $CFG->lock_factory setting to one of the other lock types included with core. These are all documented in config-dist.php.
+
+## Implementing new lock types
+
+If you really want to do this you can. I probably wouldn't recommend it - because the core lock types should be very reliable - and the performance is not really a concern.
+
+Add a new local_XXX plugin with an autoloaded class that implements \core\lock\lock_factory.
+Set the site configuration variable "lock_factory" to the full namespaced path to your class in the config.php for example
+
+```php
+$CFG->lock_factory = '\local_redis\lock\redis_lock_factory';
+```
+
+:::note
+
+See `lib/tests/lock_test.php` for an example of unit tests which can be run on a custom lock instance to verify it for correctness (run_on_lock_factory).
+
+:::
diff --git a/versioned_docs/version-5.1/apis/core/message/index.md b/versioned_docs/version-5.1/apis/core/message/index.md
new file mode 100644
index 0000000000..7d2f24ed70
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/core/message/index.md
@@ -0,0 +1,206 @@
+---
+title: Message API
+tags:
+ - API
+ - Tutorial
+ - Plugins
+ - Messaging
+---
+
+## What is this document?
+
+This document describes how to make use of the Moodle Messaging API to send messages to Moodle users.
+
+If you are after a general introduction on using the Moodle Messaging system go to [messaging user documentation](https://docs.moodle.org/en/Messaging).
+
+If you are looking for details of how the Messaging system's internal structure was implemented, go to [Messaging 2.0](https://docs.moodle.org/dev/Messaging_2.0).
+
+If you are looking for instructions on the implementation of a custom message processor (a component that receives messages sent to a user), go to [Messaging custom components](https://docs.moodle.org/dev/Messaging_custom_components).
+
+If you are looking for instructions on sending messages programmatically within Moodle then read on...
+
+## Overview
+
+Moodle components have the ability to send messages to users via the Moodle messaging system. Any type of component, for example a plugin or block, can register as a message producer then send messages to users.
+
+## File locations
+
+The Message API code is contained within `lib/messagelib.php` and is automatically included for you during page setup.
+
+## Functions
+
+`message_send()` is the primary point of contact for the message API. Call it to send a message to a user. See the php documentation for a full description of the arguments that must be supplied. There is also an example below.
+
+## Message pop-up
+
+_extend_navigation_course(
+ navigation_node $parentnode,
+ stdClass $course,
+ context_course $context
+);
+```
+
+#### User settings
+
+Any plugin implementing the following callback in `lib.php` can extend the user settings navigation.
+
+```php
+function _extend_navigation_user_settings(
+ navigation_node $parentnode,
+ stdClass $user,
+ context_user $context,
+ stdClass $course,
+ context_course $coursecontext
+);
+```
+
+#### Category settings
+
+Any plugin implementing the following callback in `lib.php` can extend the category settings navigation.
+
+```php
+function _extend_navigation_category_settings(
+ navigation_node $parentnode,
+ context_coursecat $context
+);
+```
+
+#### Frontpage settings
+
+Any plugin implementing the following callback in `lib.php` can extend the frontpage settings navigation.
+
+```php
+function _extend_navigation_frontpage(
+ navigation_node $parentnode,
+ stdClass $course,
+ context_course $context
+);
+```
+
+#### User profile
+
+Any plugin implementing the following callback in `lib.php` can extend the user profile navigation.
+
+```php
+function _extend_navigation_user(
+ navigation_node $parentnode,
+ stdClass $user,
+ context_user $context,
+ stdClass $course,
+ context_course $coursecontext
+);
+```
+
+### Boost theme
+
+The navigation API is specifically about allowing the manipulation of nodes in an in-memory tree structure that is used as the basis of building navigation components in the page. The navigation and settings blocks are 2 examples of such components and the flat navigation and settings menus in the Boost theme are another example. The navigation component itself can decide to show all or only part of the navigation tree in order to not overwhelm the user viewing the page. Whether a node is actually displayed depends on where in the tree the node was added, what is the current page in the navigation tree, and the specific navigation components that are used to provide navigation functionality in the current theme.
+
+:::important
+
+If you are testing in the Boost theme - all nodes that are added to settings tree are displayed in the course or activity settings menu. This is shown as a cog on the front page of the course or activity.
+
+Only the most important pre-selected nodes are displayed in the flat-navigation drawer in order to provide consistency and avoid overwhelming the user with too many links.
+
+It is possible, but _not recommended_, for plugins to add nodes to the flat navigation (see [FAQ's and troubleshooting](#faqs-and-troubleshooting) for more information).
+
+:::
+
+## 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:
+
+```php
+navigation_node::override_active_url(
+ new moodle_url('/your/url/here.php', [
+ 'param' => 'value',
+ ])
+);
+```
+
+### **Q.** How do I add a node to the "flat" navigation in the Boost theme?
+
+Adding a node to the "flat" navigation is only possible for Moodle versions before 4.0. After creating a node and adding it to the navigation tree - you can set the property `showinflatnavigation` to true in order for this node to be displayed in the flat navigation.
+
+```php
+$node = navigation_node::create(...);
+$node->showinflatnavigation = true;
+$navigation->add_node($node);
+```
+
+:::danger
+
+This is highly discouraged because the number of nodes in this flat navigation has been deliberately restricted to a very small number of the most important links that are applicable to all user roles.
+
+Adding more links to this menu will make it harder to use, inconsistent for different users, and inconsistent for different sites.
+
+Consider carefully if you really need to fill an additional 230x44 pixels of every single page in Moodle for every single user with a link to your thing. There are many other places to include links to your thing and most are automatically built from the navigation tree without forcing nodes to display in the flat navigation. For example, in the settings menu of a course, profile page, preferences page, reports, and so on.
+
+:::
+
+## See also
+
+- [Core APIs](../../../apis.md)
+- [Forum discussion - adding navigation to local plugins](https://moodle.org/mod/forum/discuss.php?d=170325&parent=753095)
diff --git a/versioned_docs/version-5.1/apis/core/preference/index.md b/versioned_docs/version-5.1/apis/core/preference/index.md
new file mode 100644
index 0000000000..b71b7a83fd
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/core/preference/index.md
@@ -0,0 +1,106 @@
+---
+title: Preference API
+tags:
+ - API
+ - User Preferences
+ - User
+---
+
+The Preference API is used for the storage and retrieval of user preferences. These preferences are stored in the database for users with an account, however for guests or users who are not currently logged in the preferences are stored in the Session.
+
+All of these functions operate on the current user by default, however you can specify the user you wish to operate on by passing a user ID or a moodle user object to the $user parameter. Normally this is used for state indicators, where it can be as simple as a yes or no, however you can also use it to store more complex user data, such as a serialized PHP object.
+
+It is considered good practice to abstain from storing default values as a user preference as this creates a lot of redundancy. Instead you should apply the default value at the code level if there is no stored value for a given preference.
+
+## Primary functions
+
+### get_user_preferences()
+
+This function can be used to fetch the value of a requested (via $name) preference, or if it doesn't exist the value given in the $default parameter will be returned. If you do not specify a $name then all preferences will be returned.
+
+```php
+get_user_preferences(
+ string $name = null,
+ mixed $default = null,
+ stdClass|int|null $user = null
+): mixed;
+```
+
+### set_user_preference()
+
+This function can be used to set the value of a preference named $name.
+
+```php
+set_user_preference(
+ string $name,
+ mixed $value,
+ stdClass|int|null $user = null
+): bool;
+```
+
+### set_user_preferences()
+
+This function takes an array or preferences containing the name and value for each preference. For each element in the array this function passes the keys and values of each element as the $name and $value parameters (respectively) in calls to `set_user_preferences()`.
+
+```php
+set_user_preferences(
+ array $preferences,
+ stdClass|int|null $user = null
+): bool;
+```
+
+### unset_user_preference()
+
+This deletes the requested preference, specified by the $name parameter.
+
+```php
+unset_user_preference(
+ string $name,
+ stdClass|int|null $user = null
+): bool;
+```
+
+## Example usage of the API
+
+```php title="Set a preference and then retrieve it"
+set_user_preference('foo_nameformat', 'long');
+
+// Returns the string - "long"
+get_user_preferences('foo_nameformat');
+```
+
+```php title="Set another preference and then retrieve all preferences"
+set_user_preference('foo_showavatars', 'no');
+
+// returns [
+// foo_nameformat => "long",
+// foo_showavatars => "no",
+// ];
+get_user_preferences();
+```
+
+```php title="Add an array of preferences and change foo_nameformat to short"
+$preferences = [
+ 'foo_displaynum' => '100',
+ 'foo_nameformat' => 'short',
+];
+
+set_user_preferences($preferences);
+
+// returns [
+// foo_nameformat => "short",
+// foo_showavatars => "no",
+// foo_displaynum => "100",
+// ];
+get_user_preferences();
+```
+
+```php title="Delete a preference"
+unset_user_preference('foo_showavatars');
+
+// returns [
+// foo_nameformat => "short",
+// foo_displaynum => "yes",
+// ];
+get_user_preferences();
+```
diff --git a/versioned_docs/version-5.1/apis/core/reportbuilder/_index/Actions.jpg b/versioned_docs/version-5.1/apis/core/reportbuilder/_index/Actions.jpg
new file mode 100644
index 0000000000..c8deb6d3b4
Binary files /dev/null and b/versioned_docs/version-5.1/apis/core/reportbuilder/_index/Actions.jpg differ
diff --git a/versioned_docs/version-5.1/apis/core/reportbuilder/filtering.md b/versioned_docs/version-5.1/apis/core/reportbuilder/filtering.md
new file mode 100644
index 0000000000..6a83eb1ad2
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/core/reportbuilder/filtering.md
@@ -0,0 +1,329 @@
+---
+title: Setting default conditions
+tags:
+ - Report builder
+ - reports
+---
+
+When setting up a `datasource` it is possible to define the default condition values for it using the `get_default_condition_values()` method.
+
+The method requires that you return an array where the keys are formed in a specific way so it will link to the correct filter and condition form field. The names and number of condition form fields varies depending on both the specific filter type and the operator used.
+
+The keys used in the array all start with the name of the entity you are querying followed by a colon and the name of the filter, then an underscore followed by the form field you are defining; for example, assuming we are using default names, if you have a `course_category` entity and want to set a value for the `name` filter you would need to start the keys with `course_categotry:name`.
+
+Most filter types use an `operator` for field to define which of their operators is used, they are defined as constants in each filter type, for example the text filter type has `EQUAL_TO` so you will end up with `'course_categotry:name_operator' => text::EQUAL_TO`
+
+The operator you have defined will then determine which other form fields you will need to provide values for, in our example so far that would be `value` which would be defined as `'course_categotry:name_value' => 'The name of a category'` this would mean that only a category with that exact name would be returned by default.
+
+[Core report builder filter types](https://github.com/moodle/moodle/tree/main/reportbuilder/classes/local/filters) you can find what a filter type needs by looking at their `get_sql_filter()` method.
+
+## Text filters
+
+### Operators with no additional data
+
+- `ANY_VALUE`
+- `IS_EMPTY`
+- `IS_NOT_EMPTY`
+
+## Filtering types with a single value
+
+A string should be sent in `value` for:
+
+- `CONTAINS`
+- `DOES_NOT_CONTAIN`
+- `IS_EQUAL_TO`
+- `IS_NOT_EQUAL_TO`
+- `STARTS_WITH`
+- `ENDS_WITH`
+
+```php title="Examples of array key and value pairs for single value text filters"
+'my:text_operator' => text::CONTAINS,
+'my:text_value1' => 'Bob Dylan',
+'my:text2_operator' => text::IS_NOT_EQUAL_TO,
+'my:text2_value1' => 'This exact thing',
+```
+
+## Number filter
+
+### Operators with no additional data
+
+- `ANY_VALUE`
+- `IS_NOT_EMPTY`
+- `IS_EMPTY`
+
+### Operators with a single value
+
+A number should be passed in `value1` for:
+
+- `LESS_THAN`
+- `GREATER_THAN`
+- `EQUAL_TO`
+- `EQUAL_OR_LESS_THAN`
+- `EQUAL_OR_GREATER_THAN`
+
+```php title="Examples of array key and value pairs for single value number filters"
+'my:number_operator' => number::LESS_THAN,
+'my:number_value1' => 42,
+'my:number2_operator' => number::EQUAL_OR_GREATER_THAN,
+'my:number2_value1' => 15.6,
+```
+
+### Operators with complex data
+
+#### RANGE
+
+- `value1` number for the lower bound
+- `value2` number for the upper bound
+
+```php title="Examples of array key and value pairs for range values text filters"
+'my:number_operator' => number::RANGE,
+'my:number_value1' => 60,
+'my:number_value2' => 600,
+```
+
+## Date filter
+
+The date filter has several constants used to define the amount of time:
+
+- `DATE_UNIT_MINUTE`
+- `DATE_UNIT_HOUR`
+- `DATE_UNIT_DAY`
+- `DATE_UNIT_WEEK`
+- `DATE_UNIT_MONTH`
+- `DATE_UNIT_YEAR`
+
+### Operators with no additional data
+
+- `DATE_ANY`
+- `DATE_NOT_EMPTY`
+- `DATE_EMPTY`
+- `DATE_PAST`
+- `DATE_FUTURE`
+
+### Operators with one value
+
+The `unit` should be sent defining the amount of time that should be considered.
+
+- `DATE_CURRENT`
+
+```php title="Examples of array key and value pairs for single value date filters"
+'my:date_operator' => date::DATE_CURRENT,
+'my:date_unit' => date::DATE_UNIT_DAY,
+```
+
+### Operators with two values
+
+These operators can all accept two values:
+
+1. `value` - A integer greater than 0
+2. `unit` - The type of time unit
+
+- `DATE_LAST`
+- `DATE_NEXT`
+- `DATE_BEFORE`
+- `DATE_AFTER`
+
+```php title="Examples of array key and value pairs for two value date filters"
+'my:date_operator' => date::DATE_NEXT,
+'my:date_value' => 5,
+'my:date_unit' => date::DATE_UNIT_DAY,
+'my:date2_operator' => date::DATE_BEFORE,
+'my:date2_value' => 20,
+'my:date2_unit' => date::DATE_UNIT_MINUTE,
+```
+
+### Operators with complex values
+
+#### DATE_RANGE
+
+The date range should have a unix timestamp in one or more of the following:
+
+- `from`
+- `to`
+
+```php title="Examples of array key and value pairs for the range date filters"
+'my:date_operator' => date::DATE_RANGE,
+'my:date_from' => 1732593669,
+'my:date_to' => 1732893669,
+```
+
+## Select filter
+
+### Operators with no additional data
+
+- `ANY_VALUE`
+
+### Operators with one value
+
+The value of the select should be sent in `value` to:
+
+- `EQUAL_TO`
+- `NOT_EQUAL_TO`
+
+```php title="Examples of array key and value pairs for single value select filters"
+'my:select_operator' => select::EQUAL_TO,
+'my:select_value' => 10,
+'my:select2_operator' => select::NOT_EQUAL_TO,
+'my:select2_value' => 'textkey',
+```
+
+## Boolean select filter
+
+### Operators with no additional data
+
+- `ANY_VALUE`
+- `CHECKED`
+- `NOT_CHECKED`
+
+## Duration filter
+
+For units the filter uses the standard Moodle defines:
+
+- `MINSECS`
+- `HOURSECS`
+- `DAYSECS`
+- `WEEKSECS`
+
+It also allows the integer value 1 to represent seconds.
+
+### Operators with no additional data
+
+- `DURATION_ANY`
+
+### Operators with two values
+
+These operators can all accept two values:
+
+1. `value` - A integer greater than 0, this should be the number of the units that are included.
+2. `unit` - The type of time unit.
+
+- `DURATION_MAXIMUM`
+- `DURATION_MINIMUM`
+
+```php title="Examples of array key and value pairs for two value duration filters"
+'my:duration_operator' => duration::DURATION_MAXIMUM,
+'my:duration_value' => 10,
+'my:duration_unit' => 1,
+'my:duration2_operator' => duration::DURATION_MINIMUM,
+'my:duration_value' => 42,
+'my:duration_unit' => DAYSECS,
+```
+
+## Autocomplete filter
+
+This filter type does not use `operator`, it requires that `values` contains an array of keys that the autocompletion element would return.
+
+```php title="Examples of array key and value pairs for autocomplete filters"
+'my:autocomplete_values' => [1, 4, 6],
+'my:autocomplete2_values' => [42],
+```
+
+## Category filter
+
+### Operators with complex values
+
+Both the available operators for this have two values:
+
+1. `value` The database id of a `course_category` record
+2. `subcategories` A boolean to indicate if sub categories of the selected category should also be included.
+
+- `EQUAL_TO`
+- `NOT_EQUAL_TO`
+
+```php title="Examples of array key and value pairs for category filters"
+'my:category_operator' => category::EQUAL_TO,
+'my:category_value' => [142, 4753],
+'my:category_subcategories' => true,
+'my:category2_operator' => category::NOT_EQUAL_TO,
+'my:category2_value' => [1],
+'my:category2_subcategories' => false,
+```
+
+## Course_select filter
+
+This filter type does not use `operator`, it requires that `values` contains an array of database ids for courses.
+
+```php title="Examples of array key and value pairs for course filters"
+'my:course_values' => [1, 4, 6],
+'my:course2_values' => [42],
+```
+
+## Cohort filter
+
+This filter type does not use `operator`, it requires that `values` contains an array of database ids for cohorts.
+
+```php title="Examples of array key and value pairs for cohort filters"
+'my:cohort_values' => [1, 4, 6],
+'my:cohort2_values' => [42],
+```
+
+## Filesize filter
+
+The filter defines several units for filesize as constants:
+
+- `SIZE_UNIT_KILOBYTE`
+- `SIZE_UNIT_MEGABYTE`
+- `SIZE_UNIT_GIGABYTE`
+
+### Operators with no additional data
+
+- `ANY_VALUE`
+
+### Operators with two values
+
+1. `value1` The size of the file in the unit
+2. `unit` The type of unit (as defined by the filter constants)
+
+- `LESS_THAN`
+- `GREATER_THAN`
+
+```php title="Examples of array key and value pairs for two value file size filters"
+'my:filesize_operator' => filesize::LESS_THAN,
+'my:filesize_value1' => 50,
+'my:filesize_unit' => filesize::SIZE_UNIT_KILOBYTE,
+'my:filesize2_operator' => filesize::GREATER_THAN,
+'my:filesize2_value1' => 1,
+'my:filesize2_unit' => filesize::SIZE_UNIT_GIGABYTE,
+```
+
+## Tags filter
+
+### Operators with no additional data
+
+- `ANY_VALUE`
+- `NOT_EMPTY`
+- `EMPTY`
+
+### Operators with one value
+
+An array of tag database ids should be sent in `value` to:
+
+- `EQUAL_TO`
+- `NOT_EQUAL_TO`
+
+```php title="Examples of array key and value pairs for single value tag filters"
+'my:tags_operator' => tags::EQUAL_TO,
+'my:tags_value' => [142, 4753],
+'my:tags2_operator' => tags::NOT_EQUAL_TO,
+'my:tags2_value' => [1],
+```
+
+## User filter
+
+### Operators with no additional data
+
+- `USER_ANY`
+- `USER_CURRENT`
+
+### Operators with one value
+
+An array of user database ids should be sent in `value` to:
+
+- `USER_SELECT`
+
+```php title="Examples of array key and value pairs for single value user filters"
+'my:user_operator' => user::USER_SELECT,
+'my:user_value' => [142, 4753],
+'my:user2_operator' => user::USER_SELECT,
+'my:user2_value' => [1],
+```
diff --git a/versioned_docs/version-5.1/apis/core/reportbuilder/index.md b/versioned_docs/version-5.1/apis/core/reportbuilder/index.md
new file mode 100644
index 0000000000..30723aecf3
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/core/reportbuilder/index.md
@@ -0,0 +1,643 @@
+---
+title: Report builder API
+tags:
+ - Report builder
+ - reports
+---
+
+## Overview
+
+### Introduction
+
+The report builder API is a way of providing reporting data, with paging, filtering, exporting standardized across them in both system and custom reports. Once the groundwork is done in defining the report elements in entities, it's possible to implement them with minimal code just by adding entities to the report, and defining which elements you want to use from them.
+
+### Column
+
+#### Column overview
+
+Column instances define the data captured/displayed within a report column typically:
+
+- How the data is retrieved, either a simple SQL table.field fragment or an expression that returns a value
+- They type of data that is being retrieved (int, text, datetime, etc)
+- How that data should be presented in a report (for instance calling userdate() on datetime types)
+
+#### Column types
+
+- `Text`
+- `Integer` (Integer numbers)
+- `Float` (Decimal numbers)
+- `Timestamp` (Dates)
+- `Boolean` (Yes / No values)
+- `Longtext`
+
+#### Creating columns
+
+To create a new column, just create a new instance of [`reportbuilder/classes/local/report/column.php`](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/report/column.php) class with:
+
+```php
+* string $name
+* ?lang_string $title
+* string $entityname
+```
+
+And use:
+
+- `add_joins()` to add any extra SQL joins the column might need
+- `set_type()` to add the column type (All constant types are defined within the same column class)
+- `set_is_sortable()` to define if column can be sorted (For example we don't want to sort if the column shows just a picture)
+- `add_callback()` to format the output of the column
+- `add_field()` to add any db fields format callback might need
+- `set_is_deprecated()` used to mark a column as deprecated, indicating it will be removed in the future. This is required in core Moodle columns if you want delete or remove one from an entity because plugins may be using the fields.
+
+```php title="Example of code for creating a column"
+$columns[] = (new column(
+ 'starttime',
+ new lang_string('task_starttime', 'admin'),
+ $this->get_entity_name()
+ ))
+ ->add_joins($this->get_joins())
+ ->set_type(column::TYPE_TIMESTAMP)
+ ->add_field("{$tablealias}.timestart")
+ ->set_is_sortable(true)
+ ->add_callback([format::class, 'userdate']);
+```
+
+### Filter
+
+#### Filter overview
+
+Report filters can be defined for a report and allow users to narrow down (filter) the data that is displayed in a report:
+
+- They define the data being filtered, either a simple SQL fragment or expression.
+- The type of filtering being performed (int, text, datetime, etc).
+Filter types are extendable, allowing for the addition of many more as suit each use case.
+We have provided common ones that cover most use cases.
+
+:::note
+
+Filters & columns are entirely separate concepts in the report, and each can be used without a matching column/filter (that is to say, we can add a report filter for a user field without needing the column for the same field to be present in the report).
+
+:::
+
+#### Filter types
+
+- **Text** ([reportbuilder/classes/local/filters/text.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/filters/text.php))
+- **Date** ([reportbuilder/classes/local/filters/date.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/filters/date.php))
+- **Number** ([reportbuilder/classes/local/filters/number.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/filters/number.php))
+- **Boolean Select** ([reportbuilder/classes/local/filters/boolean_select.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/filters/boolean_select.php))
+- **Select** ([reportbuilder/classes/local/filters/select.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/filters/select.php))
+- **Course selector** ([reportbuilder/classes/local/filters/course_selector.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/filters/course_selector.php))
+- **Duration** ([reportbuilder/classes/local/filters/duration.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/filters/duration.php))
+- **Tags** ([reportbuilder/classes/local/filters/tags.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/filters/tags.php))
+- **Autocomplete** ([reportbuilder/classes/local/filters/autocomplete.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/filters/autocomplete.php))
+- **Category** ([reportbuilder/classes/local/filters/category.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/filters/category.php))
+
+#### Creating filters
+
+To create a new filter, just create a new instance of **[reportbuilder/classes/local/report/filter.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/report/filter.php)** class with:
+
+```php
+* string $filterclass
+* string $name
+* lang_string $header
+* string $entityname
+* string $fieldsql = ''
+* array $fieldparams = []
+```
+
+```php title="Example of code for creating a filter"
+$filters[] = (new filter(
+ course_selector::class,
+ 'courseselector',
+ new lang_string('courses'),
+ $this->get_entity_name(),
+ "{$tablealias}.id"
+ ))
+ ->add_joins($this->get_joins());
+```
+
+### Entity
+
+#### Entity overview
+
+Entities are simply collections of report elements (currently columns and filters). They allow for common elements to be defined once, and then re-used in all reports - developers can choose to use as many or as few of the elements from each entity as required. We have provided user and course entities. They can be joined to reports using standard SQL query syntax.
+
+All report elements can be defined within the reports themselves - but entities mean it's much easier to create re-usable components, and will also help in the long term with custom reports.
+
+#### Create an entity
+
+To create an entity, the new entity class must extend **[reportbuilder/classes/local/entities/base.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/entities/base.php)** class and must include these methods:
+
+```php
+get_default_tables()
+get_default_entity_title()
+initialise()
+```
+
+If creating an entity for core Moodle data it should be located in one of the following namespaces:
+
+- `\core_reportbuilder\local\entities\`
+- `reportbuilder\local\entities` sub namespace of the subsystem the data is from, for example [`core_course\reportbuilder\local\entities\course_category`](https://github.com/moodle/moodle/blob/main/course/classes/reportbuilder/local/entities/course_category.php)
+
+When creating one for your own plugin you could technically put it anywhere, however to make it easy to find you should probably use a sub namespace like:
+
+- `reportbuilder\local\entities`
+- `reportbuilder\entities`
+
+For example if you were building a entity to show assignments you might make it's full namespace `\mod_assign\reportbuilder\entities\assignments`.
+
+##### get_default_tables()
+
+Defines all the database tables that must be present in the main SQL or joins added to the entity.
+
+##### get_default_entity_title()
+
+Defines the default title for this entity.
+
+##### initialise()
+
+This is where we **add** the entity columns and filters.
+
+#### Tips
+
+Always add all the entities joins to each of its columns and filters; also ensure you add them before any other joins.
+
+If you do not do add these joins when the entity is not being used as the main one there will be SQL errors when they are used.
+
+If you do not add them before other joins when the entity is not the main one in a report, you may find that any references to the primary table of the entity in your additional joins break.
+
+```php title="Adding entity joins to a column"
+$column->add_joins($this->get_joins())
+```
+
+When writing any SQL snippets you should always use the alias table aliases that are returned by the `get_table_alias()` method, this is because reports using the column can change the alias used by a table.
+
+```php title="Example of getting the alias for a table"
+$logalias = $this->get_table_alias('logstore_standard_log');
+$useralias = $this->get_table_alias('user');
+$fildname = "{$useralias).lastname";
+$join = "JOIN {user} {$useralias} ON {$useralias}.id = {$logalias}.relateduser"
+```
+
+#### Examples
+
+Check out these two entities as an example to start building reports:
+
+- **User entity**: [reportbuilder/classes/local/entities/user.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/entities/user.php)
+- **Course entity**: [reportbuilder/classes/local/entities/course.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/local/entities/course.php)
+
+### Actions
+
+
+
+Report actions can be defined in system reports to provide CTA links for each row in the report. Using `:placeholder` elements in the action URLs allows them to be specific to the row content. For example, to always provide a link to the current user/course of the current row
+
+```php
+ $this->add_action((new action(
+ new moodle_url('/admin/tasklogs.php', ['logid' => ':id']),
+ new pix_icon('e/search', ''),
+ [],
+ true,
+ new lang_string('viewtasklog', 'report_tasklogs')
+ )));
+```
+
+## System reports
+
+System reports are a consistent way of providing reporting data, with paging, filtering, exporting standardized across them. Once the groundwork is done in defining the report elements in entities, it's possible to implement them with minimal code just by adding entities to the report, and defining which elements you want to use from them
+
+### Create a new system report using entities
+
+To create a new system report just create a new class extending [reportbuilder/classes/system_report.php](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/system_report.php).
+
+The first method that we need is ***initialise()*** :
+
+```php
+/**
+* Initialise report, we need to set the main table, load our entities and set columns/filters
+*/
+protected function initialise(): void {
+```
+
+The initialise method needs to get the main entity, set the main table it needs to use and add the entity to the report:
+
+```php
+// Our main entity, it contains all of the column definitions that we need.
+$entitymain = new task_log();
+$entitymainalias = $entitymain->get_table_alias('task_log');
+
+$this->set_main_table('task_log', $entitymainalias);
+$this->add_entity($entitymain);
+```
+
+After that, if the report will have 'Actions', it needs to define the columns these actions will use:
+
+```php
+$this->add_base_fields("{$entitymainalias}.id");
+```
+
+Now, after adding our first entity, the report can use the columns and filters from it OR more entities can be added to the report using SQL joins:
+
+```php
+$entityuser = new user();
+$entituseralias = $entityuser->get_table_alias('user');
+$this->add_entity($entityuser->add_join(
+ "LEFT JOIN {user} {$entituseralias} ON {$entituseralias}.id = {$entitymainalias}.userid"
+));
+```
+
+Once all entities have been added it needs to define which columns it needs to show **in the order we need**:
+
+```php
+$columns = [
+ 'task_log:name',
+ 'task_log:type',
+ 'user:fullname',
+ 'task_log:starttime',
+];
+
+$this->add_columns_from_entities($columns);
+```
+
+After defining the columns, it needs to define all the filters (or empty array for no filters) that it will use:
+
+```php
+$filters = [
+ 'task_log:name',
+ 'task_log:result',
+ 'task_log:timestart',
+];
+
+$this->add_filters_from_entities($filters);
+```
+
+In case it needs actions for each report row, they can be defined like:
+
+```php
+// Action to download individual task log.
+$this->add_action((new action(
+ new moodle_url('/admin/tasklogs.php', ['logid' => ':id', 'download' => true]),
+ new pix_icon('t/download', ''),
+ [],
+ new lang_string('downloadtasklog', 'report_tasklogs')
+)));
+```
+
+:::info
+
+Note that the placeholders used here (:id in this example) have been previously added using **add_base_fields**();
+
+:::
+
+Once the whole report has been defined, is possible to set if the report will be downloadable or not:
+
+```php
+$this->set_downloadable(true);
+```
+
+### Use an entity
+
+### Override display name for a column
+
+It's possible to override the display name of a column, if you don't want to use the value provided by the entity.
+
+```php
+if ($column = $this->get_column('user:fullname')) {
+ $column->set_title(new lang_string('user', 'admin'));
+}
+```
+
+### Set a default initial sort direction
+
+It's possible to set a default initial sort direction for one column.
+
+```php
+$this->set_initial_sort_column('task_log:starttime', SORT_DESC);
+```
+
+### Examples
+
+Check out these two system reports as an example:
+
+- **Task logs**: [`admin/classes/reportbuilder/local/systemreports/task_logs.php`](https://github.com/moodle/moodle/blob/main/admin/classes/reportbuilder/local/systemreports/task_logs.php)
+- **Config changes**: [`report/configlog/classes/reportbuilder/local/systemreports/config_changes.php`](https://github.com/moodle/moodle/blob/main/report/configlog/classes/reportbuilder/local/systemreports/config_changes.php)
+
+## Custom reports
+
+The custom reporting interface allows reports to be built with a custom view for users, Moodle and plugins can define data sources that provide the basis for the reports that users can make using the system.
+
+### Create a new data source using entities
+
+To create a data source you need to extend [`\core_reportbuilder\datasource`](https://github.com/moodle/moodle/blob/main/reportbuilder/classes/datasource.php). Your class must be located in the `reportbuilder\datasource` namespace of your plugin or the Moodle subsystem it is for.
+
+The first method you need to build is `initialise()`
+
+```php
+/**
+* Initialise report, we need to set the main table, load our entities and set columns/filters
+*/
+protected function initialise(): void {
+```
+
+The initialise method needs to get the main entity, set the main table it needs to use and add the entity to the report:
+
+```php
+// Our main entity, it contains all of the column definitions that we need.
+$entitymain = new task_log();
+$entitymainalias = $entitymain->get_table_alias('task_log');
+
+$this->set_main_table('task_log', $entitymainalias);
+$this->add_entity($entitymain);
+```
+
+Now, after adding our first entity, the report can use the columns and filters from it OR more entities can be added to the report using SQL joins:
+
+```php
+$entityuser = new user();
+$entityuseralias = $entityuser->get_table_alias('user');
+$entityuser->add_join(
+ "LEFT JOIN {user} {$entityuseralias} ON {$entityuseralias}.id = {$entitymainalias}.userid"
+);
+$this->add_entity($entityuser);
+```
+
+If you are adding an entity that does not directly join to the entity containing the main table you will need to add the joins to all the intermediate entities to it, without this if a user adds a column from the table to a custom report and has not also added a column from the intermediate table there will be an error.
+
+```php
+$entitycourse = new course();
+$entitycoursealias = $entityuser->get_table_alias('course');
+$entitycourse->add_join("JOIN {course} {$entitycoursealias} ON {$entitycoursealias}.id = {$entityactivity}.course");
+
+$entitycategory = new course_category();
+$entitycategoryalias = $entityuser->get_table_alias('course_category');
+$entitycategory->add_joins($entitycourse->get_joins());
+$entitycategory->add_join("JOIN {course_category} {$entitycategoryalias} ON {$entitycategoryalias}.id = {$entitycoursealias}.category");
+```
+
+If you are using the same sort of entity twice, or they happen to have clashing aliases in another entity, you can set the alias for a table in an entity:
+
+```php
+$entityuser2 = new user();
+$entityuser2->set_table_alias('user', 'u2');
+```
+
+Next you need to add the columns, filters and conditions that a user can add to the custom report. If you want everything you can use:
+
+```php
+$this->add_all_from_entities();
+```
+
+### Setup report name
+
+You will need to specify the name that is displayed to the end user for the data source.
+
+```php
+ /**
+ * Return user friendly name of the report source
+ *
+ * @return string
+ */
+ public static function get_name(): string {
+ return get_string('tasklogs', 'core_admin');
+ }
+```
+
+### Setup default columns
+
+Once all entities have been added you need to define which columns it will show by default **they will be displayed in the order you define them**, by implementing the `get_default_columns()` method:
+
+```php
+/**
+ * Return the columns that will be added to the report upon creation
+ *
+ * @return string[]
+ */
+public function get_default_columns(): array {
+ return [
+ 'task_log:name',
+ 'task_log:starttime',
+ 'task_log:duration',
+ 'task_log:result',
+ ];
+}
+```
+
+You may also optionally define the sorting that will be applied to the default report, **it must only use default columns** by overriding the `get_default_column_sorting()` method:
+
+```php
+/**
+ * Return the column sorting that will be added to the report upon creation
+ *
+ * @return int[]
+ */
+public function get_default_column_sorting(): array {
+ return [
+ 'task_log:starttime' => SORT_DESC,
+ ];
+}
+```
+
+### Setup default filters
+
+The filters allow the end user of the report to only see a subset of the data the report will normally show. You need to define the default setup for this using the `get_default_filters()` method.
+
+```php
+/**
+ * Return the filters that will be added to the report upon creation
+ *
+ * @return string[]
+ */
+public function get_default_filters(): array {
+ return [
+ 'task_log:timestart',
+ 'task_log:result',
+ ];
+}
+```
+
+### Setup conditions
+
+The conditions allow the user creating the report to define which data it will return. You need to define the default setup for this using the `get_default_conditions()` method.
+
+```php
+/**
+ * Return the conditions that will be added to the report upon creation
+ *
+ * @return string[]
+ */
+public function get_default_conditions(): array {
+ return [
+ 'task_log:type',
+ 'task_log:timestart',
+ 'task_log:result',
+ ];
+}
+```
+
+You may also optionally define the [initial values for any of the default conditions](./filtering.md) by overriding the `get_default_condition_values()` method.
+
+```php
+/**
+ * Return the condition values that will be set for the report upon creation
+ *
+ * @return array
+ */
+public function get_default_condition_values(): array {
+ return [
+ 'task_log:type_operator' => select::EQUAL_TO,
+ 'task_log:type_value' => \core\task\database_logger::TYPE_SCHEDULED,
+ ];
+}
+```
+
+### Adding unit tests
+
+Data sources have a specific type of testcase `\core_reportbuilder_testcase` that provides several useful utility methods that will help you ensure that the data source and it's entities are working correctly.
+
+```php
+defined('MOODLE_INTERNAL') || die();
+
+global $CFG;
+require_once("{$CFG->dirroot}/reportbuilder/tests/helpers.php");
+
+/**
+ * Unit tests for course categories datasource
+ *
+ * @package core_course
+ * @covers \core_course\reportbuilder\datasource\categories
+ * @copyright 2023 Paul Holden
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class categories_test extends core_reportbuilder_testcase {
+```
+
+The `core_reportbuilder_testcase` will not autoload so we first ensure that it is loaded with the `require_once`. After this there are a few things you should look to test:
+
+1. That the default report setup works properly
+2. That you can add all the columns that are not defined in the default report
+3. That the filters work
+4. Add the stress tests
+
+#### Testing the default report
+
+For this you want a step that sets up will return enough data allows you test all the ordering you have configured for the report.
+
+```php
+ /**
+ * Test default datasource
+ */
+ public function test_datasource_default(): void {
+ $this->resetAfterTest();
+
+ $category = $this->getDataGenerator()->create_category(['name' => 'Zoo', 'idnumber' => 'Z01']);
+ $course = $this->getDataGenerator()->create_course(['category' => $category->id]);
+
+ /** @var core_reportbuilder_generator $generator */
+ $generator = $this->getDataGenerator()->get_plugin_generator('core_reportbuilder');
+ $report = $generator->create_report(['name' => 'My report', 'source' => categories::class, 'default' => 1]);
+
+ $content = $this->get_custom_report_content($report->get('id'));
+ $this->assertCount(2, $content);
+
+ // Default columns are name, idnumber, coursecount. Sorted by name ascending.
+ $this->assertEquals([
+ [get_string('defaultcategoryname'), '', 0],
+ [$category->get_formatted_name(), $category->idnumber, 1],
+ ], array_map('array_values', $content));
+ }
+```
+
+In this example an additional category has been added to Moodle, the category has had a course added to it so that the count of courses in the category can also be tested.
+
+It then creates a custom report and gets it's data before testing:
+
+- It has the expected number of rows
+- Testing after stripping out the array keys that the data returned is in the correct order and formatted correctly
+
+#### Testing the non-default columns and filtering
+
+You can create blank report can be created by passing `'default' => 0` to the `create_report()` method of the `core_reportbuilder` data generator:
+
+```php
+$report = $generator->create_report(['name' => 'My report', 'source' => categories::class, 'default' => 0]);
+```
+
+to add columns of data to the report you would use the `create_column()` method:
+
+```php
+$generator->create_column(['reportid' => $report->get('id'), 'uniqueidentifier' => 'course_category:path']);
+```
+
+it is possible to add sorting to the column by passing additional data in the array, for example:
+
+```php
+$generator->create_column(
+ [
+ 'reportid' => $report->get('id'),
+ 'uniqueidentifier' => 'course_category:path'
+ 'sortenabled' => true,
+ 'sortdirection' => SORT_ASC,
+ 'sortorder' => 1,
+ ]
+);
+```
+
+This would cause the column to be sorted ascending. You need to use `sortorder` to decide on the priority it is given in the sorting, with lower numbers being given priority.
+
+To add a filter to the report you would use the `create_filter()` method of the `core_reportbuilder` data generator:
+
+```php
+$generator->create_filter(['reportid' => $report->get('id'), 'uniqueidentifier' => 'user:firstname']);
+```
+
+This will add the filter for the user's firstname. When you generate the report you will need to pass an array of conditions as the third parameter:
+
+```php
+$filtervalues = [
+ 'user:firstname_operator' => text::IS_EQUAL_TO,
+ 'user:firstname_value' => 'Pedro',
+];
+$content = $this->get_custom_report_content($report->get('id'), 0, $filtervalues);
+```
+
+This would cause the report to return results for users with the first name of _Pedro_ only.
+
+#### The stress test
+
+The stress test uses helper methods which:
+
+- Add and remove every column individually from a report and ensures that is still returns data without error, it also tests the column can be sorted if that has been enabled.
+- Individually aggregates a report on each column
+- Individually applies each filter
+
+None of these tests checks that the data is what you want, but will ensure that all your joins are setup correctly for the `datasource` to work without errors when manipulating it via the custom report interface.
+
+```php
+ /**
+ * Stress test datasource
+ *
+ * In order to execute this test PHPUNIT_LONGTEST should be defined as true in phpunit.xml or directly in config.php
+ */
+ public function test_stress_datasource(): void {
+ if (!PHPUNIT_LONGTEST) {
+ $this->markTestSkipped('PHPUNIT_LONGTEST is not defined');
+ }
+
+ $this->resetAfterTest();
+
+ $category = $this->getDataGenerator()->create_category(['name' => 'My category']);
+
+ $this->datasource_stress_test_columns(categories::class);
+ $this->datasource_stress_test_columns_aggregation(categories::class);
+ $this->datasource_stress_test_conditions(categories::class, 'course_category:idnumber');
+ }
+```
+
+The test first sets up some data that the data source can return, it then uses three helper methods provided by `core_reportbuilder_testcase`
+
+The first parameter for each method is the fully qualified class name of the `datasource` that should be tested. `datasource_stress_test_conditions()` has a second parameter that must be the name of a column from the `datasource`.
+
+#### Unit test examples
+
+- **Course categories** [`/course/tests/reportbuilder/datasource/categories_test.php`](https://github.com/moodle/moodle/blob/main/course/tests/reportbuilder/datasource/categories_test.php)
+- **Badges** [`/badges/tests/reportbuilder/datasource/badges_test.php`](https://github.com/moodle/moodle/blob/main/badges/tests/reportbuilder/datasource/badges_test.php)
diff --git a/versioned_docs/version-5.1/apis/core/user/index.md b/versioned_docs/version-5.1/apis/core/user/index.md
new file mode 100644
index 0000000000..06b30c1b59
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/core/user/index.md
@@ -0,0 +1,123 @@
+---
+title: User-related APIs
+tags:
+ - User
+documentationDraft: true
+---
+
+This is a collection of miscellaneous APIs that can help with doing things with lists of users.
+
+:::note
+
+Please note that, in many cases, more specific APIs may be more appropriate, for example:
+
+- [Access API](../../subsystems/access.md)
+- [Groups API](../../subsystems/group/index.md)
+- [Enrolment API](../../subsystems/enrol.md)
+
+:::
+
+## User field display
+
+The [User fields](https://docs.moodle.org/dev/User_fields) class is mainly used when displaying tables of data about users. It indicates which extra fields (e.g. email) should be displayed in the current context based on the permissions of the current user. It also provides ways to get the necessary data from a query, and to obtain other generally-useful fields for user names and pictures.
+
+`.
+For example: `aiplacement_editor` (with a corresponding namespace).
+
+Each Placement **must** inherit from the `\core_ai\placement` abstract class.
+They must also implement the following methods:
+
+**`get_action_list(): array`**
+
+This is the list of Actions that are supported by this Placement, for example the `aiplacement_editor` plugin defines this as:
+
+```php
+public function get_action_list(): array {
+ return [
+ \core_ai\aiactions\generate_text::class,
+ \core_ai\aiactions\generate_image::class,
+ ];
+}
+```
+
+## Capabilities and permissions
+
+Placements provide a way for a user to carry out an Action.
+Placements are responsible for determining who can use a particular Action, and where it can be used.
+It is not the job of Providers to determine access.
+
+```php
+$capabilities = [
+ 'aiplacement/editor:generate_image' => [
+ 'captype' => 'write',
+ 'contextlevel' => CONTEXT_COURSE,
+ 'archetypes' => [
+ 'manager' => CAP_ALLOW,
+ 'editingteacher' => CAP_ALLOW,
+ 'teacher' => CAP_ALLOW,
+ 'student' => CAP_ALLOW,
+ ],
+ ],
+...
+```
+
+## Action processing
+
+The following is the basic workflow in order for a placement to have an action processed for a user request:
+
+```mermaid
+sequenceDiagram
+ Placement->>Manager: New action
+ Manager->>Provider: Process action
+ Provider->>Manager: Get response
+ Manager->>Placement: Pass response
+```
+
+### Step 1
+
+- The Placement instantiates a new Action object of type they wish to use.
+- The Action must be instantiated with the required data. Each action will define what configuration it needs. As an example:
+
+```php
+// Prepare the action.
+$action = new \core_ai\aiactions\generate_image(
+ contextid: $contextid,
+ userid: $USER->id,
+ prompttext: $prompttext,
+ quality: $quality,
+ aspectratio: $aspectratio,
+ numimages: $numimages,
+ style: $style,
+);
+```
+
+### Step 2
+
+- The Placement then instantiates the Manager class `core_ai\manager`.
+- The Manager calls `process_action()`, passing in the configured Action object. As an example:
+
+```php
+// Send the action to the AI manager.
+$manager = \core\di::get(\core_ai\manager::class);
+$response = $manager->process_action($action);
+```
+
+### Step 3
+
+- The `process_action()` method then returns a response object (instance of `responses\response_base`).
+- It is up to the Placement to check for success/failure of the response and pass the result back to the
+ user.
+
+## Plugin structure
+
+The Placement plugins reside in the `ai/placement` directory.
+
+Each Placement is in a separate subdirectory and consists of a number of mandatory and supportive files that will
+be necessary for development.
+
+`.
+For example: `aiprovider_openai`, or `aiprovider_azureai` (with a corresponding namespace).
+
+Each Provider **must** inherit from the `\core_ai\provider` abstract class.
+
+### Required Methods
+
+They must also implement the following methods:
+
+**`get_action_list(): array`**
+
+This is the list of Actions that are supported by this Provider, for example the `aiprovider_openai` plugin defines this as:
+
+```php
+public static function get_action_list(): array {
+ return [
+ \core_ai\aiactions\generate_text::class,
+ \core_ai\aiactions\generate_image::class,
+ \core_ai\aiactions\summarise_text::class,
+ ];
+}
+```
+
+**`is_provider_configured(): bool`**
+
+Each provider will need to specify what it takes to be considered as configured.
+It is likely that each provider will have a set of keys necessary to access the external AI API.
+
+The `is_provider_configured()` must return `true` for UI component visibility and functionality. If not overridden, it will
+return `false` by default.
+
+For example, the `aiprovider_azureai` provider checks values are set for `$this->apikey` and `$this->apiendpoint` and returns
+the result.
+
+```php
+public function is_provider_configured(): bool {
+ return !empty($this->config['apikey']) && !empty($this->config['endpoint']);
+}
+```
+
+## Process classes
+
+For each action supported by the provider, the provider plugin **must** implement a `process_` class,
+where `` is the name of the action. For example: `process_generate_image`.
+
+Every process action class **must** inherit from the `\core_ai\process_base` abstract class.
+
+The process action class **must** implement a `process()` method. This method is responsible for
+converting the data requested by an Action into the format needed by the external AI services API,
+and then correctly providing the response back from the AI in an Action Response object.
+
+The process action classes and process method are expected by the manager to exist and be callable.
+
+As most provider plugins will support more than one action, it is recommended to create an
+`abstract_processor` class that inherits from the `\core_ai\process_base` class and then have each
+process action class inherit from this abstract class.
+
+For example, the `aiprovider_openai` plugin defines an `abstract_processor` class that inherits from
+the `\core_ai\process_base` class and then the `process_generate_image`, `process_generate_text` and
+`process_summarise_text` classes inherit from this abstract class.
+
+This can be visualised as follows:
+
+```mermaid
+graph TD;
+ A[process_base] --> B[abstract_processor]
+ B[abstract_processor] --> C[process_generate_image]
+ B --> D[process_generate_text]
+ B --> E[process_summarise_text]
+ ```
+
+Apart from this, Providers are free to define their own structure. It should be kept in mind that Providers
+are designed to be a 'thin wrapper' around the external AI systems API. They shouldn't store data,
+or have their own UI elements (beyond what is required for configuration).
+
+## Plugin structure
+
+Provider plugins reside in the `ai/provider` directory.
+
+Each Provider is in a separate subdirectory and consists of a number of mandatory files and any other
+files the developer is going to use.
+
+` method.
+
+This method should define the settings form for the provider plugin, using the provided `mform` object.
+
+For example, the `aiprovider_openai` plugin defines this:
+
+```php
+namespace aiprovider_openai;
+use core_ai\hook\after_ai_provider_form_hook;
+
+class hook_listener {
+
+ /**
+ * Hook listener for the Open AI instance setup form.
+ *
+ * @param after_ai_provider_form_hook $hook The hook to add to the AI instance setup.
+ */
+ public static function set_form_definition_for_aiprovider_openai(after_ai_provider_form_hook $hook): void {
+ if ($hook->plugin !== 'aiprovider_openai') {
+ return;
+ }
+
+ $mform = $hook->mform;
+
+ // Required setting to store OpenAI API key.
+ $mform->addElement(
+ 'passwordunmask',
+ 'apikey',
+ get_string('apikey', 'aiprovider_openai'),
+ ['size' => 75],
+ );
+ $mform->addHelpButton('apikey', 'apikey', 'aiprovider_openai');
+ $mform->addRule('apikey', get_string('required'), 'required', null, 'client');
+
+ // Setting to store OpenAI organization ID.
+ $mform->addElement(
+ 'text',
+ 'orgid',
+ get_string('orgid', 'aiprovider_openai'),
+ ['size' => 25],
+ );
+ $mform->setType('orgid', PARAM_TEXT);
+ $mform->addHelpButton('orgid', 'orgid', 'aiprovider_openai');
+
+ }
+
+}
+```
+
+Because a hook is used to define the settings, Provider plugins also need to have a `db/hooks.php` file to register its hook callback.
+The specified plugin callback method is called whenever the provider instance is chosen in the provider administration settings.
+
+For example, the `aiprovider_openai` plugin defines this:
+
+```php
+defined('MOODLE_INTERNAL') || die();
+
+$callbacks = [
+ [
+ 'hook' => \core_ai\hook\after_ai_provider_form_hook::class,
+ 'callback' => \aiprovider_openai\hook_listener::class . '::set_form_definition_for_aiprovider_openai',
+ ],
+];
+```
+
+## Action Settings
+
+Each of the actions that a provider plugin supports can have its own settings.
+If an action requires additional settings, the provider class for the plugin should override the `get_action_settings()` method.
+The method must return an instance of `core_ai\form\action_settings_form`.
+
+For example, the `aiprovider_openai` plugin defines this:
+
+```php
+#[\Override]
+public static function get_action_settings(
+ string $action,
+ array $customdata = [],
+): action_settings_form|bool {
+ $actionname = substr($action, (strrpos($action, '\\') + 1));
+ $customdata['actionname'] = $actionname;
+ $customdata['action'] = $action;
+ if ($actionname === 'generate_text' || $actionname === 'summarise_text') {
+ return new form\action_generate_text_form(customdata: $customdata);
+ } else if ($actionname === 'generate_image') {
+ return new form\action_generate_image_form(customdata: $customdata);
+ }
+
+ return false;
+}
+```
+
+The actual settings form for the actions should be defined in the `classes/form` directory.
+For example, the `aiprovider_openai` plugin defines `action_generate_text_form` and `action_generate_image_form` classes.
+These classes should extend the `core_ai\form\action_settings_form` class, and must implement the `definition()` method.
+
+For example, the `aiprovider_openai` plugin defines this:
+
+```php
+class action_generate_text_form extends action_settings_form {
+ #[\Override]
+ protected function definition() {
+ $mform = $this->_form;
+ $actionconfig = $this->_customdata['actionconfig']['settings'] ?? [];
+ $returnurl = $this->_customdata['returnurl'] ?? null;
+ $actionname = $this->_customdata['actionname'];
+ $action = $this->_customdata['action'];
+ $providerid = $this->_customdata['providerid'] ?? 0;
+
+ // Action model to use.
+ $mform->addElement(
+ 'text',
+ 'model',
+ get_string("action:{$actionname}:model", 'aiprovider_openai'),
+ 'maxlength="255" size="20"',
+ );
+ $mform->setType('model', PARAM_TEXT);
+ $mform->addRule('model', null, 'required', null, 'client');
+ $mform->setDefault('model', $actionconfig['model'] ?? 'gpt-4o');
+ $mform->addHelpButton('model', "action:{$actionname}:model", 'aiprovider_openai');
+
+...
+```
+
+## Predefined models
+
+Pre-defined models allow AI providers to define specific model configurations that can be selected by users.
+This provides a better user experience by offering known model options with appropriate default parameters rather than requiring manual configuration.
+
+### Creating Model Classes
+
+To implement pre-defined models, you will need to create model classes in the `[your_plugin]/classes/aimodel` directory and extend the `core_ai\aimodel\base` class.
+
+For example, `aiprovider_openai` plugin defines this:
+
+```php
+namespace aiprovider_openai\aimodel;
+
+use core_ai\aimodel\base;
+use MoodleQuickForm;
+
+class gpt4o extends base implements openai_base {
+ #[\Override]
+ public function get_model_name(): string {
+ return 'gpt-4o';
+ }
+
+ #[\Override]
+ public function get_model_display_name(): string {
+ return 'GPT-4o';
+ }
+
+ // Add other model-specific methods or properties
+}
+```
+
+### Implementing Per-Model Settings
+
+To add configurable settings for individual models:
+
+1. Override the `has_model_settings()` and `add_model_settings()` methods:
+
+ ```php
+ #[\Override]
+ public function has_model_settings(): bool {
+ return true;
+ }
+
+ #[\Override]
+ public function add_model_settings(MoodleQuickForm $mform): void {
+ $mform->addElement(
+ 'text',
+ 'top_p',
+ get_string('settings_top_p', 'aiprovider_openai'),
+ );
+ $mform->setType('top_p', PARAM_FLOAT);
+ $mform->addHelpButton('top_p', 'settings_top_p', 'aiprovider_openai');
+
+ // Add more model settings as needed
+ $mform->addElement(
+ 'text',
+ 'max_tokens',
+ get_string('settings_max_tokens', 'aiprovider_openai'),
+ );
+ $mform->setType('max_tokens', PARAM_INT);
+ }
+ ```
+
+2. Create a helper class to manage models. For example, the `aiprovider_openai` plugin defines this:
+
+ ```php
+ namespace aiprovider_openai;
+
+ class helper {
+ /**
+ * Get all model classes.
+ *
+ * @return array Array of model classes
+ */
+ public static function get_model_classes(): array {
+ $models = [];
+ $modelclasses = \core_component::get_component_classes_in_namespace('aiprovider_openai', 'aimodel');
+ foreach ($modelclasses as $class => $path) {
+ if (!class_exists($class) || !is_a($class, \core_ai\aimodel\base::class, true)) {
+ throw new \coding_exception("Model class not valid: {$class}");
+ }
+ $models[] = $class;
+ }
+ return $models;
+ }
+
+ /**
+ * Get a specific model class instance.
+ *
+ * @param string $modelname The model name
+ * @return \core_ai\aimodel\base|null The model class or null if not found
+ */
+ public static function get_model_class(string $modelname): ?\core_ai\aimodel\base {
+ foreach (self::get_model_classes() as $modelclass) {
+ $model = new $modelclass();
+ if ($model->get_model_name() === $modelname) {
+ return $model;
+ }
+ }
+ return null;
+ }
+ }
+ ```
+
+### Integrating with Action Settings Forms
+
+To add model settings to action forms, you will need to create a hook listener that adds the model settings to the action form.
+
+For example, the `aiprovider_openai` plugin does these:
+
+1. Create a hook listener that adds model settings to the action form:
+
+ ```php
+ public static function set_model_form_definition_for_aiprovider_openai(after_ai_action_settings_form_hook $hook): void {
+ if ($hook->plugin !== 'aiprovider_openai') {
+ return;
+ }
+
+ $mform = $hook->mform;
+ if (isset($mform->_elementIndex['modeltemplate'])) {
+ $model = $mform->getElementValue('modeltemplate');
+ if (is_array($model)) {
+ $model = $model[0];
+ }
+
+ // Handle custom model option.
+ if ($model == 'custom') {
+ $mform->addElement('header', 'modelsettingsheader', get_string('settings', 'aiprovider_openai'));
+ $mform->addElement(
+ 'textarea',
+ 'modelextraparams',
+ get_string('extraparams', 'aiprovider_openai'),
+ ['rows' => 5, 'cols' => 20],
+ );
+ $mform->setType('modelextraparams', PARAM_TEXT);
+ } else {
+ // Handle pre-defined model settings.
+ $targetmodel = helper::get_model_class($model);
+ if ($targetmodel && $targetmodel->has_model_settings()) {
+ $mform->addElement('header', 'modelsettingsheader', get_string('settings', 'aiprovider_openai'));
+ $targetmodel->add_model_settings($mform);
+ }
+ }
+ }
+ }
+ ```
+
+2. Register the hook callback in `db/hooks.php`:
+
+ ```php
+ $callbacks = [
+ [
+ 'hook' => \core_ai\hook\after_ai_action_settings_form_hook::class,
+ 'callback' => \aiprovider_openai\hook_listener::class . '::set_model_form_definition_for_aiprovider_openai',
+ ],
+ ];
+ ```
+
+### Model Selection UI
+
+To create a model selector UI for your action settings form, you will need to add the model selector element to your action settings form.
+
+For example, `aiprovider_openai` plugin defines this:
+
+```php
+// Create model selector options
+$models = [];
+foreach (helper::get_model_classes() as $modelclass) {
+ $model = new $modelclass();
+ $models[$model->get_model_name()] = $model->get_model_display_name();
+}
+$models['custom'] = get_string('custom_model', 'aiprovider_openai');
+
+$mform->addElement(
+ 'select',
+ 'modeltemplate',
+ get_string('model_template', 'aiprovider_openai'),
+ $models
+);
+$mform->setDefault('modeltemplate', 'gpt-4o');
+```
+
+## Rate limiting
+
+Provider plugins by default implement rate limiting to prevent abuse of the external AI services.
+This is inherited from the `core_ai\provider` class. Developers don't need to implement rate limiting themselves.
+
+This default rate limiting behaviour can be changed by overriding the `is_request_allowed()` method `core_ai\provider` class.
diff --git a/versioned_docs/version-5.1/apis/plugintypes/antivirus/_files/scanner-php.mdx b/versioned_docs/version-5.1/apis/plugintypes/antivirus/_files/scanner-php.mdx
new file mode 100644
index 0000000000..0b614a3177
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/antivirus/_files/scanner-php.mdx
@@ -0,0 +1,13 @@
+
+
+
+The `classes/scanner.php` class must be defined in the correct namespace for your plugin, and must extend the `\core\antivirus\scanner` class.
+
+It is responsible for implementing the interface between Moodle and the antivirus scanning tool.
+
+The following methods are compulsory:
+
+- `is_configured(): bool` - returns true, if this antivirus plugin is configured.
+- `scan_file($file, $filename, $deleteinfected): void` - performs the **$file** scanning using antivirus functionality, using **$filename** as filename string in any reporting, deletes infected file if **$deleteinfected** is true.
+
+If a virus is found the `scan_file()` function _must_ throw an instance of the `\core\antivirus\scanner_exception` type.
diff --git a/versioned_docs/version-5.1/apis/plugintypes/antivirus/_files/scanner-php.tsx b/versioned_docs/version-5.1/apis/plugintypes/antivirus/_files/scanner-php.tsx
new file mode 100644
index 0000000000..167d78e6ff
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/antivirus/_files/scanner-php.tsx
@@ -0,0 +1,88 @@
+/**
+ * Copyright (c) Moodle Pty Ltd.
+ *
+ * Moodle is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Moodle is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Moodle. If not, see
+
+
+
+This is where all the functionality for this plugin is defined. We will step through this file and describe each part as we go.
+
+```php
+class assign_submission_file extends assign_submission_plugin {
+```
+
+All submission plugins MUST define a class with the component name of the plugin that extends assign_submission_plugin.
+
+#### get_name()
+
+```php
+public function get_name() {
+ return get_string('file', 'assignsubmission_file');
+}
+```
+
+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()
+
+```php
+public function get_settings(MoodleQuickForm $mform) {
+ global $CFG, $COURSE;
+
+ $defaultmaxfilesubmissions = $this->get_config('maxfilesubmissions');
+ $defaultmaxsubmissionsizebytes = $this->get_config('maxsubmissionsizebytes');
+
+ $settings = [];
+ $options = [];
+ 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[] = [
+ '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'
+ );
+}
+```
+
+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()
+
+```php
+public function save_settings(stdClass $data) {
+ $this->set_config('maxfilesubmissions', $data->assignsubmission_file_maxfiles);
+ $this->set_config('maxsubmissionsizebytes', $data->assignsubmission_file_maxsizebytes);
+ return true;
+}
+```
+
+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()
+
+```php
+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(), ['class' => 'accesshide']),
+ null,
+ $fileoption
+ );
+
+ return true;
+}
+```
+
+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()
+
+```php
+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;
+ }
+```
+
+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()
+
+```php
+public function get_files($submission) {
+ $result = [];
+ $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;
+}
+```
+
+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()
+
+```php
+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
+ );
+ }
+
+ return get_string('countfiles', 'assignsubmission_file', $count);
+}
+```
+
+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()
+
+```php
+public function view($submission) {
+ return $this->assignment->render_area_files(
+ 'assignsubmission_file',
+ ASSIGNSUBMISSION_FILE_FILEAREA,
+ $submission->id
+ );
+}
+```
+
+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.
+
+#### submission_summary_for_email()
+
+```php
+#[\Override]
+public function submission_summary_for_messages(stdClass $submission): array {
+ global $PAGE;
+
+ $onlinetextsubmission = $this->get_onlinetext_submission($submission->id);
+ if (!$onlinetextsubmission || !$onlinetextsubmission->onlinetext) {
+ return ['', ''];
+ }
+
+ $renderer = $PAGE->get_renderer('mod_assign');
+ $templatecontext = ['wordcount' => count_words($onlinetextsubmission->onlinetext)];
+ return [
+ // Mustache strips off all trailing whitespace, but we want a newline at the end.
+ $renderer->render_from_template(
+ 'assignsubmission_onlinetext/notification_text', $templatecontext) . "\n",
+ $renderer->render_from_template(
+ 'assignsubmission_onlinetext/notification_html', $templatecontext),
+ ];
+}
+```
+
+This method produces a summary of what was submitted, in a form suitable to include in messages (for example, the 'You have submitted' confirmation). Moodle messages can be plain text or HTML, so you need to prepare both. It is recommended to use templates so themes can override it if they want to. As you produce your output, think about the fact that multiple Submission plugins may be in use at the same time, in which case your summary will appear alongside other summaries.
+
+#### can_upgrade()
+
+```php
+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;
+}
+```
+
+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()
+
+```php
+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;
+ }
+
+ 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,
+ ['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,
+ ['id' => $this->assignment->get_instance()->id]
+ );
+ return true;
+ }
+}
+```
+
+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()
+
+```php
+public function upgrade($oldcontext, $oldassignment, $oldsubmission, $submission, &$log) {
+ global $DB;
+
+ $filesubmission = (object) [
+ 'numfiles' => $oldsubmission->numfiles,
+ 'submission' => $submission->id,
+ 'assignment' => $this->assignment->get_instance()->id,
+ ];
+
+ if (!$DB->insert_record('assign_submission_file', $filesubmission) > 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;
+}
+```
+
+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()
+
+```php
+public function () {
+ return [
+ 'onlinetext' => get_string('pluginname', 'assignsubmission_comments'),
+ ];
+}
+```
+
+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()
+
+```php
+public function get_editor_text($name, $submissionid) {
+ if ($name == 'onlinetext') {
+ $onlinetextsubmission = $this->get_onlinetext_submission($submissionid);
+ if ($onlinetextsubmission) {
+ return $onlinetextsubmission->onlinetext;
+ }
+ }
+
+ return '';
+}
+```
+
+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()
+
+```php
+public function get_editor_format($name, $submissionid) {
+ if ($name == 'onlinetext') {
+ $onlinetextsubmission = $this->get_onlinetext_submission($submissionid);
+ if ($onlinetextsubmission) {
+ return $onlinetextsubmission->onlineformat;
+ }
+ }
+
+ return 0;
+}
+```
+
+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()
+
+```php
+public function is_empty(stdClass $submission) {
+ return $this->count_files($submission->id, ASSIGNSUBMISSION_FILE_FILEAREA) == 0;
+}
+```
+
+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.
+
+#### submission_is_empty()
+
+```php
+public function submission_is_empty() {
+ global $USER;
+ $fs = get_file_storage();
+
+ // Get a count of all the draft files, excluding any directories.
+ $files = $fs->get_area_files(
+ context_user::instance($USER->id)->id,
+ 'user',
+ 'draft',
+ $data->files_filemanager,
+ 'id',
+ false
+ );
+
+ return count($files) == 0;
+}
+```
+
+Determine if a submission is empty. This is distinct from is_empty() in that it is intended to be used to determine if a submission made before saving is empty.
+
+#### get_file_areas()
+
+```php
+public function get_file_areas() {
+ return [ASSIGNSUBMISSION_FILE_FILEAREA=>$this->get_name()];
+}
+```
+
+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()
+
+```php
+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 = ['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;
+}
+```
+
+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()
+
+```php
+public function format_for_log(stdClass $submission) {
+ // Format the information for each submission plugin add_to_log
+ $filecount = $this->count_files($submission->id, ASSIGNSUBMISSION_FILE_FILEAREA);
+ return ' the number of file(s) : ' . $filecount . " file(s).
"; +} +``` + +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() + +```php +public function delete_instance() { + global $DB; + // Will throw exception on failure + $DB->delete_records('assignsubmission_file', [ + 'assignment'=>$this->assignment->get_instance()->id, + ]); + + return true; +} +``` + +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. + +## 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. + +## Other features + +### Add calendar events + +
+
+## Features flags can control generation of optional files/code fragments.
+features:
+ readme: true
+ license: true
+
+ ## Privacy API implementation
+privacy:
+ haspersonaldata: false
+ uselegacypolyfill: false
+
+block_features:
+ ## Creates the file edit_form.php
+ edit_form: true
+
+ ## Allows multiple instances of the block on the same course.
+ instance_allow_multiple: false
+
+ ## Choose where to display the block.
+ applicable_formats:
+ - page: all
+ allowed: false
+ - page: course-view
+ allowed: true
+ - page: course-view-social
+ allowed: false
+
+ ## Backup the block plugin.
+ backup_moodle2:
+ restore_task: true
+ restore_stepslib: true
+ backup_stepslib: true
+ settingslib: true
+ backup_elements:
+ - name: elt
+ restore_elements:
+ - name: elt
+ path: /path/to/file
+
+## Capabilities defined by the plugin.
+capabilities:
+ ## Required by block plugins.
+ - name: myaddinstance
+ title: Add a new pluginname block to the My dashboard
+ captype: write
+ contextlevel: CONTEXT_SYSTEM
+ archetypes:
+ - role: user
+ permission: CAP_ALLOW
+ clonepermissionsfrom: moodle/my:manageblocks
+
+ - name: addinstance
+ title: Add a new pluginname block
+ captype: write
+ contextlevel: CONTEXT_BLOCK
+ archetypes:
+ - role: editingteacher
+ permission: CAP_ALLOW
+ - role: manager
+ permission: CAP_ALLOW
+ clonepermissionsfrom: moodle/site:manageblocks
+
+## Explicitly added strings
+lang_strings:
+ - id: mycustomstring
+ text: You can add 'extra' strings via the recipe file.
+ - id: mycustomstring2
+ text: Another string with {$a->some} placeholder.
diff --git a/versioned_docs/version-5.1/apis/plugintypes/blocks/index.md b/versioned_docs/version-5.1/apis/plugintypes/blocks/index.md
new file mode 100644
index 0000000000..a71a7df1f2
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/blocks/index.md
@@ -0,0 +1,436 @@
+---
+title: Block plugins
+tags:
+ - Blocks
+ - Tutorial
+ - Plugins
+---
+
+import {
+ Lang,
+ VersionPHP,
+ DbAccessPHP,
+} from '../../_files';
+import { ComponentFileSummary } from '../../../_utils';
+
+Block plugins allow you to show supplemental information, and features, within different parts of Moodle.
+
+## File structure
+
+Blocks plugins are located in the `/blocks` directory.
+
+Each plugin is in a separate subdirectory and consists of a number of _mandatory files_ and any other files the developer is going to use.
+
+
+
+
+```php
+class block_pluginname extends block_base {
+
+ // (...)
+
+ public function get_content() {
+ if ($this->content !== null) {
+ return $this->content;
+ }
+
+ $this->content = new stdClass;
+ $this->content->text = 'The content of pluginname block';
+ $this->content->footer = 'Footer here...';
+
+ return $this->content;
+ }
+}
+```
+
+
+
+
+```php
+class block_pluginname extends block_list {
+
+ // (...)
+
+ public function get_content() {
+ global $OUTPUT;
+ if ($this->content !== null) {
+ return $this->content;
+ }
+
+ $this->content = (object) [
+ 'items' => [],
+ 'icons' => [],
+ 'footer' => 'Footer here...',
+ ];
+
+ $this->content->items[] = 'An item of pluginname block';
+ $this->content->icons[] = $OUTPUT->pix_icon('i/course', get_string('course'));
+
+ // Add more list items here.
+
+ return $this->content;
+ }
+}
+```
+
+
+
+
+:::caution
+
+The get_content can be called several times during the page rendering. To prevent your class from calculating it every time your plugin should check if $this->content is already defined at the beginning of the method.
+
+:::
+
+:::tip
+
+If the block content is empty (an empty string) the block will not be displayed. In the case of an extending block_base block this means empty the `$this->content->text` and the `$this->content->footer` values. In a block_list block, the `$this->content->items` array should be empty. Moodle performs this check by calling the block's `is_empty()` method, and if the block is indeed empty then it is not displayed at all.
+
+:::
+
+### applicable_formats(): array
+
+Blocks can be added to any kind of page. However, some blocks may only be displayed on certain page types. This method is used to define the page types that the block can be displayed on. See [Limit the block to specific contexts](#limit-the-block-to-specific-contexts) section below for more information.
+
+### instance_allow_multiple()
+
+By default, only one instance of each block plugin can be added to a page. However, if your plugin allows multiple instances you can overrdie the instance_allow_multiple method.
+
+
+The plugin lib.php must contain the plugin base class.
+
+
+Enrolment plugins must extend `enrol_plugin` base class which is defined at the end of lib/enrollib.php. This base class contains all standard methods to define the plugin workflow.
+
+### lang/en/enrol_pluginname.php
+
+import langExample from '!!raw-loader!./_examples/enrol_lang.php';
+
+
+
+## Features flags can control generation of optional files/code fragments.
+features:
+ readme: true
+ license: true
+
+ ## Privacy API implementation
+privacy:
+ haspersonaldata: false
+ uselegacypolyfill: false
+
+format_features:
+ # Create the Moodle 4.0+ basic template structure.
+ basic_outputs: true
+
+ # General format features.
+ uses_sections: true
+ uses_course_index: true
+ uses_indentation: false
+ uses_inplace_editor: true
+ uses_reactive_components: true
+ uses_news: true
+
+## Explicitly added strings
+lang_strings:
+ - id: mycustomstring
+ text: You can add 'extra' strings via the recipe file.
+ - id: mycustomstring2
+ text: Another string with {$a->some} placeholder.
+
+ ## Needed for course format plugins.
+ - id: addsections
+ text: Add section
+ - id: currentsection
+ text: This section
+ - id: editsection
+ text: Edit section
+ - id: editsectionname
+ text: Edit section name
+ - id: deletesection
+ text: Delete section
+ - id: newsectionname
+ text: New name for section {$a}
+ - id: sectionname
+ text: Section
+ - id: hidefromothers
+ text: Hide section
+ - id: showfromothers
+ text: Show section
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/renderer.php b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/renderer.php
new file mode 100644
index 0000000000..a29a9cad99
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/renderer.php
@@ -0,0 +1,41 @@
+namespace format_pluginname\output;
+
+use core_courseformat\base as format_base;
+use core_courseformat\output\section_renderer;
+use moodle_page;
+
+/**
+* Basic renderer for pluginname format.
+*
+* @copyright 2022 Someone
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+ class renderer extends section_renderer {
+ // Override any necessary renderer method here.
+
+ /**
+ * Generate the section title, wraps it in a link to the section page if page is to be displayed on a separate page.
+ *
+ * This method is required to enable the inplace section title editor.
+ *
+ * @param section_info|stdClass $section The course_section entry from DB
+ * @param stdClass $course The course entry from DB
+ * @return string HTML to output.
+ */
+ public function section_title($section, $course) {
+ return $this->render(format_base::instance($course)->inplace_editable_render_section_name($section));
+ }
+
+ /**
+ * Generate the section title to be displayed on the section page, without a link.
+ *
+ * This method is required to enable the inplace section title editor.
+ *
+ * @param section_info|stdClass $section The course_section entry from DB
+ * @param int|stdClass $course The course entry from DB
+ * @return string HTML to output.
+ */
+ public function section_title_without_link($section, $course) {
+ return $this->render(format_base::instance($course)->inplace_editable_render_section_name($section, false));
+ }
+ }
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_files/course_editor_workflow.png b/versioned_docs/version-5.1/apis/plugintypes/format/_files/course_editor_workflow.png
new file mode 100644
index 0000000000..c4013b05fd
Binary files /dev/null and b/versioned_docs/version-5.1/apis/plugintypes/format/_files/course_editor_workflow.png differ
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_files/course_format_output.png b/versioned_docs/version-5.1/apis/plugintypes/format/_files/course_format_output.png
new file mode 100644
index 0000000000..794c0dd84c
Binary files /dev/null and b/versioned_docs/version-5.1/apis/plugintypes/format/_files/course_format_output.png differ
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/index.md b/versioned_docs/version-5.1/apis/plugintypes/format/index.md
new file mode 100644
index 0000000000..17bd62b136
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/index.md
@@ -0,0 +1,815 @@
+---
+title: Course format
+tags:
+ - Plugins
+ - Format
+---
+
+
+
+
+
+
+import { getExample } from '@site/src/moodleBridge';
+import { ComponentFileSummary } from '../../../_utils';
+import {
+ Lang,
+ Lib,
+ VersionPHP,
+} from '../../_files';
+
+Course formats are plugins that determine the layout of course resources.
+
+Course formats determine how the course main page looks like (/course/view.php) in both view and editing mode. They are also responsible for building a navigation tree inside the course (displayed to users in the navigation block, course index, and breadcrumb). They can organize the course content in sections. The course creator or teacher can specify the course format for the course in the course edit form.
+
+Course formats also can add their own options fields to the course edit form. They can add course-dependent content to the header/footer of any page inside the course, not only /course/view.php
+
+## File structure
+
+All course format files must be located inside the **course/format/pluginname** folder.
+
+
+The main library of the format. It should contain a class `format_pluginname` extending `core_courseformat\base`, this class is known as the format base class. Also, it may contain callbacks for other core and contributed APIs if necessary.
+
+
+The format base class is the most important part of the course format as it defines how the format interacts with both frontend and backend. Depending on the methods a format plugin overrides the course will behave in different ways.
+
+### lang/en/format_pluginname.php
+
+import langExample from '!!raw-loader!./_examples/format_lang.php';
+
+
`course_format_uses_sections()` that invokes it. It affects default navigation tree building. Various modules and reports may call this function to know whether to display the section name for the particular module or not. | +| `get_default_section_name()` | This method gets the default section name if the user has not provided a value for the section name. In format_base, it basically calls `get_section_name()`, which returns the `$string['sectionname']` + the section number of the current section, if available, or blank, otherwise. It can be used in conjunction with your course format's `get_section_name()` implementation. For reference, please refer to the implementations in format_topics and format_weeks classes. | +| `get_section_name()` | Returns the name for a particular section. This function may be called often so it should use only fields cached in section_info object (field course_sections.name is always cached)
In 3.0+, it checks if the `$string['sectionname']` is available in the lang file. If the section name string is not available, it returns an empty string. | +| `get_view_url()` | Returns the URL for a particular section, it can be either anchored on course view page or separate page. See parent function PHPdocs for more details | +| `is_section_current()` | Specifies if the section is current, for example, current week or highlighted topic. This function is only used if your renderer uses it for example if your renderer extends format_section_renderer_base. This function is not called from anywhere else in Moodle core. | +| `get_section_highlighted_name()` | Return the textual label for a current/highlighted section.| +| `set_section_number()` | Setup the format base instance to display a single section instead of all. This method is used to prepare the format base instance to render the course. | +| `get_section_number()` | Return zero if the course will deploy all sections or a section number if the current page is only presenting a single section. | +| `get_course_display()` | Return `COURSE_DISPLAY_SINGLEPAGE` or `COURSE_DISPLAY_MULTIPAGE` depending if the course has multiple section per page or not. | +| `get_last_section_number()` | Returns the last section | +| `page_title()` | Formats can override this method to alter the page title. | + +### Course features + +The format base class has several methods to integrate the course format with the frontend course editor and its webservices. + +| `core_courseformat\base` Overridable method | Description | +|---|---| +| `ajax_section_move()` | Code executed after sections were rearranged using drag and drop. See the example in format_topics where sections have automatic names depending on their sequence number | +| `uses_course_index()` | Return true if the course format is compatible with the course index drawer. Note that classic based themes are not compatible with the course index. | +| `uses_indentation()` | If the format uses the legacy activity indentation. | +| `supports_components()` | Since Moodle 4.0 the course is rendered using reactive UI components. This kind of component will be the only standard in Moodle 4.3+ but, until then, formats can override this method to specify if they want to use the previous UI elements or the new ones. | +| `supports_news()` | Determine if the news forum is mandatory or not on the course format. | +| `get_default_blocks()` | Course format can specify which blocks should be added to the course page when the course is created in this format.
If the course format is changed during course edit, blocks are not changed.
Whatever course format specifies in the method, site admin can override it with `$CFG->defaultblocks_override` or `$CFG->defaultblocks_pluginname` | +| `extend_course_navigation()` | This function is called when a navigation tree is built.
Node for the course will be created in navigationlib for you and all standard available branches like 'Participants' or 'Reports' will be added to it. After that course format can add nodes for sections and modules. There is a default implementation that adds branches for course sections and modules under them. Or if the course format does not use sections, all modules will just be placed under course mode. The course format is able to override the default navigation tree building.
Note that if navigationlib can not find the node for the current course module, the node will be added automatically (after this callback). | + +### Course format options + +The core table `course_format_options` in Moodle database is designed to store additional options for course formats. Those options may belong for the whole course or just for course section. + +Course format options must not have the same names as fields in database table `course`, section options must not have the same names as fields in `course_sections`. Also, make sure names do not duplicate completion and conditional fields in edit forms. + +When the teacher changes the course format in the course edit form AND the old and the new course formats share the same option name, the value of this option is copied from one format to another. For example, if the course had format Topics and had 8 sections in it and teacher changes format to Weeks, the course will have 8 weeks in it. + +During backup the course format options are stored as if they were additional fields in `course` table. Do not store IDs of elements (courses, sections, etc.) in course format options because they will not be backed up and restored properly. You can use section numbers because they are relative inside the course. If absolute ids are necessary you can create your own backup/restore scripts, see Backup API. + +Webservices expect course format options to be passed in additional entities but for backward compatibility `numsections`, `hiddensections` and `coursedisplay` can also be passed as if they were fields in `course` table. + +| `core_courseformat\base` Overridable method | Description | +|---|---| +| `course_format_options()` | By overriding this method course format specifies which additional options it has for course | +| `section_format_options()` | By overriding this method course format specifies which additional options it has for course section. Note that since section information is cached you may want to cache some additional options as well. See PHPdocs for more information | +| `get_format_options()` | (usually no need to override) low level function to retrieve course format options values. It is more convenient to use methods get_course() and get_section() | +| `create_edit_form_elements()` | This function is called to alter course edit form and standard section edit form. The default implementation creates simple form elements for each option defined in either `course_format_options()` or `section_format_options()`. Overwrite it if you want to have more comprehensive form elements or if you do not want options to appear in edit forms, etc. | +| `edit_form_validation()` | Overwrite if course format plugin needs additional validation for it's option in course edit form | +| `update_format_options()` | (usually no need to override) low level function to insert/update records in db table `course_format_options` | +| `update_course_format_options()` | updates course format options with the data from the edit course form. The plugin can override for example to include calculated options fields, especially when the course format is being changed. For example, format_topics and format_weeks automatically fill field `numsections` when the user switches from other format | +| `update_section_format_options()` | updates course format options for the section with the data from the edit section form | +| `editsection_form()` | Return an instance of moodleform to edit a specified section. Default implementation returns instance of `editsection_form` that automatically adds additional fields defined in section_format_options() | +| `get_default_course_enddate()` | Overwrite if the course format is time-based. The base class calculates the default course end date based on the number of sections. | +| `delete_format_data()` | This hook method is called when the course is deleted and can be used to remove any course data not stored in the standards `course_format_options` and `course` tables (like user preferences, for example). | + +Course format base helpers +The format base class is used for all the core_courseformat integrations, from settings to rendering. All course output classes will receive the course format instance as a primary param and the class has several helper methods to get information about the format. + +| `core_courseformat\base` Overridable method | Description | +|---|---| +| `get_course()` | (no need to override) returns object with all fields from db table `course` AND all course format options | +| `get_section()` | (no need to override) returns instance of section_info. It will contain all fields from table `course_sections` and all course format options for this section | +| `get_sections()` | Return all course sections (it is just a wrapper fo the modinfo get_section_info_all) | +| `get_course_display()` | Returns if the course is using a multi page or a single page display (`COURSE_DISPLAY_MULTIPAGE` or `COURSE_DISPLAY_SINGLEPAGE`) | +| `get_modinfo()` | Returns the current course modinfo (equivalent to get_fast_modinfo but without specifying the course) | +| `get_renderer()` | Return the course format renderer instance | +| `get_output_classname()` | This method gets a relative output class path (for example, "content\\section") and returns the correct output class namespace depending on if the format has overridden outputs or not. See [overriding output classes](#override-output-classes) section for more information. | +| `is_section_current()` | Returns if a specific section is marked as current (highlighted) or not. | +| `show_editor()` | Do all the user and page validations to know if the current course display has to include editor options or not. This includes both page editing mode and user capabilities. You can pass an array of capabilities which should be checked. If none specified, will default to `moodle/course:manageactivities`. | + +## Rendering a course + +Each format plugin is responsible for rendering the course in the format.php file, this means each plugin can choose how to render the course content. However, there are some conventions on how a course should be rendered to integrate the plugin with the existing components. + +The course rendering is done using four mains elements: + +- **File view.php:** responsible for setting up the format base instance and rendering the content. +- **Course format renderer:** all format plugins must provide its own version of the `core_courseformat\output\section_renderer` (or provide an equivalent class with all the necessary methods). +- **Output classes:** by default all course elements have a specific output class inside course/format/output/local folder. Each one of them is responsible for generating the necessary data to render the templates. Format plugins can provide alternative versions of those output classes (see [override output classes](#override-output-classes) for more information) +- **Mustache templates:** each output class has its equivalent mustache template inside course/format/templates. All the course content is rendered using a single "content" template that includes all the rest as sub-templates. For this reason, a plugin that wants to override some templates must provide some extra templates in order to keep the template structure. See [Creating the basic output structure](#creating-the-basic-output-structure) section for more information. + +Unless there's a reason for it, the course structure should be rendered overriding the standard outputs and mustache templates. + +## Format output classes and templates + +The following diagram shows the standard output classes structure: + + + +There are three renderer methods used for refreshing fragments of the course page: + +- **render_content:** used to render the full course. This method is not necessary as the content output itself will be used by default. +- **course_section_updated:** needed when the frontend needs to render a particular section. It is used mostly when a new section is created. By default it renders the core_courseformat\output\local\content\section output. +- **Course_section_updated_cm_item:** used every time the frontend needs to update an activity card on the course page. By default it will render the core_courseformat\output\local\content\section\cmitem. The reason why it uses this specific output is that it renders the full course module list item, not just the activity card. + +By default, the base renderer methods will use the format output components to render the full course. In case your plugins have special needs, it is possible to override those three methods directly into the format renderer class. + +### Override output classes + +Instead of having several renderer methods on a single file, the core_courseformat subsystem splits the output logic through several small classes, each one for a specific UI component. Format plugins can easily override specific classes to alter the template data. + +The course format base class has a special method called **get_output_classname** that returns the overridden class name if available in the format plugin (or the core one if not). In order to detect the format classes, your plugin must place the overridden one in the equivalent path inside your plugin format_pluginname\output\courseformat\ folder + +For example, if a format plugin wants to add new options to the section action menu it should override the core_courseformat\output\local\content\section\controlmenu. To do so the plugin class should be format_pluginname\output\courseformat\content\section\controlmenu. You can find an example of an overridden output in the "course/format/topics/classes/output/courseformat/content/section/controlmenu.php" file. + +### Creating the basic output structure + +By default, the course renderer will use the core_courseformat output classes and templates. To override some parts of the course elements the plugin must provide a minimum output classes and template structure. + +#### Basic output classes + +It is recommended your plugin overrides the 3 main course format elements: + +- format_pluginname\output\courseformat\content +- format_pluginname\output\courseformat\content\section +- format_pluginname\output\courseformat\content\section\cmitem + +Those output classes should extend the equivalent core ones but, at least, they should override the **get_template_name** method to redirect the rendering template to the overridden template. It could also override the export_for_template to alter the template data if necessary. +This is the minimum output classes your plugin must provide: + +
+
+
+import OutputContent from '!!raw-loader!./_examples/output/content.php';
+export const OutputContentProps = {
+ examplePurpose: 'Output content',
+ plugintype: 'format',
+ pluginname: 'pluginname',
+ filepath: '/output/courseformat/content.php',
+};
+
+
+
+
+import OutputSection from '!!raw-loader!./_examples/output/section.php';
+export const OutputSectionProps = {
+ examplePurpose: 'Output section',
+ plugintype: 'format',
+ pluginname: 'pluginname',
+ filepath: '/output/courseformat/content/section.php',
+};
+
+
+
+
+import OutputCmitem from '!!raw-loader!./_examples/output/cmitem.php';
+export const OutputCmitemProps = {
+ examplePurpose: 'Output cmitem',
+ plugintype: 'format',
+ pluginname: 'pluginname',
+ filepath: '/output/courseformat/content/section/cmitem.php',
+};
+
+
+
+
+#### Basic template files
+
+Unlike output classes, mustache files cannot be extended nor overridden. To be able to alter specific mustaches your plugin must provide a minimum template structure. To allow partial overriding, the core_courseformat template uses blocks instead of inclusions to include sub templates.
+
+This is the minimum template structure your plugin must provide:
+
+
+
+
+import TemplateContent from '!!raw-loader!./_examples/output/content.mustache';
+
+{TemplateContent}
+
+
+
+
+import TemplateSection from '!!raw-loader!./_examples/output/section.mustache';
+
+{TemplateSection}
+
+
+
+
+import TemplateCmitem from '!!raw-loader!./_examples/output/cmitem.mustache';
+
+{TemplateCmitem}
+
+
+
+
+### Override mustache blocks
+
+Once your plugin has the basic mustache structure, you can provide extra mustache blocks to override parts of the page. To do so it is important to understand first the special way in which the course format mustaches are included.
+
+Most moodle mustache files include sub-templates by doing `{{> path/to/the/template }}`. However, in the course format subsystems, all sub-templates are loaded using a slightly different pattern.
+
+
message body
'; +$message->smallmessage = 'small message'; +$message->notification = 1; // Because this is a notification generated from Moodle, not a user-to-user message +$message->contexturl = (new \moodle_url('/course/'))->out(false); // A relevant URL for the notification +$message->contexturlname = 'Course list'; // Link title explaining where users get to for the contexturl +// Extra content for specific processor +$content = [ + '*' => [ + 'header' => ' test ', + 'footer' => ' test ', + ], +]; +$message->set_additional_content('email', $content); + +// You probably don't need attachments but if you do, here is how to add one +$usercontext = context_user::instance($user->id); +$file = new stdClass(); +$file->contextid = $usercontext->id; +$file->component = 'user'; +$file->filearea = 'private'; +$file->itemid = 0; +$file->filepath = '/'; +$file->filename = '1.txt'; +$file->source = 'test'; + +$fs = get_file_storage(); +$file = $fs->create_file_from_string($file, 'file1 content'); +$message->attachment = $file; + +// Actually send the message +$messageid = message_send($message); +``` + +```php title="Before 2.9 message data used to be a stdClass object as shown below (This formation of a message will no longer work as of Moodle 3.6. Only a message object will be accepted):" + +$message = new stdClass(); +$message->component = 'mod_quiz'; //your component name +$message->name = 'submission'; //this is the message name from messages.php +$message->userfrom = $USER; +$message->userto = $touser; +$message->subject = $subject; +$message->fullmessage = $message; +$message->fullmessageformat = FORMAT_PLAIN; +$message->fullmessagehtml = ''; +$message->smallmessage = ''; +$message->notification = 1; //this is only set to 0 for personal messages between users +message_send($message); +``` + +### How to set-up the message pop-up + +Here is example code showing you how to set-up the JavaScript pop-up link. + +```php +require_once('message/lib.php'); +$userid = 2; +$userto = $DB->get_record('user', ['id' => $userid]); + +message_messenger_requirejs(); +$url = new moodle_url('message/index.php', ['id' => $userto->id]); +$attributes = message_messenger_sendmessage_link_params($userto); +echo html_writer::link($url, 'Send a message', $attributes); +``` + +## Changes in Moodle 3.5 + +
+
+
+## Settings
+
+Settings for the Placement should be defined in the `settings.php` file.
+Each Placement plugin should create a new admin settings page using `core_ai\admin\admin_settingspage_provider` class.
+
+This is the same for Provider plugins, for example:
+
+```php
+use core_ai\admin\admin_settingspage_provider;
+
+if ($hassiteconfig) {
+ // Placement specific settings heading.
+ $settings = new admin_settingspage_provider(
+ 'aiplacement_courseassist',
+ new lang_string('pluginname', 'aiplacement_courseassist'),
+ 'moodle/site:config',
+ true,
+ );
+...
+```
diff --git a/versioned_docs/version-5.1/apis/plugintypes/ai/provider.md b/versioned_docs/version-5.1/apis/plugintypes/ai/provider.md
new file mode 100644
index 0000000000..0420c73874
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/ai/provider.md
@@ -0,0 +1,476 @@
+---
+title: Providers
+tags:
+ - AI
+ - LLM
+ - Provider
+---
+
+Providers are the interface between the [AI subsystem](/apis/subsystems/ai/index.md) and external AI.
+Their focus should be on converting the data requested into the format needed
+by the external AI, and then correctly providing the response back.
+
+Incoming data to the Provider plugin arrives via the Manager `core_ai\manager`.
+The Manager is the connective tissue between the Provider and the [Placement](/apis/plugintypes/ai/placement.md) plugins.
+Likewise, all responses from the Provider plugin are handed back to the Manager before being passed to the Placement plugin.
+
+A Provider plugin allows many "provider instances" to be defined, each of which can support a different set of configurations.
+This facilitates having providers for specific tasks. So, you can use a more efficient model for lightweight tasks like summarisation, and a more fully featured model for text generation. Another example is defaulting to using a cheaper model with a lower token limit, and then falling back to a more expensive model if a request is too large for the default model.
+
+:::warning The Golden Rule:
+
+Placements **do not** know about Providers, and Providers **do not** know about Placements.
+Everything should go via the Manager.
+
+:::
+
+## Class implementation
+
+Providers are defined as classes in their own namespace according to their plugin name.
+The naming convention for a Provider class is `aiprovider_The typical directory layout for the Placement plugin, using the Editor Placement as an example:
+ +```console +. +├── classes +│ ├── external +│ │ ├── generate_image.php +│ │ └── generate_text.php +│ ├── placement.php +│ ├── privacy +│ │ └── provider.php +│ └── utils.php +├── db +│ ├── access.php +│ └── services.php +├── lang +│ └── en +│ └── aiplacement_editor.php +├── tests +│ └── utils_test.php +└── version.php +``` + +
+
+
+## Provider Settings
+
+Settings for the Provider are defined as a [Hook](/apis/core/hooks/index.md).
+Each Provider plugin should create a new `classes/hook_listener.php` file. This file should contain a class with a static method that defines the hook callback.
+create a new admin settings page using `core_ai\admin\admin_settingspage_provider` class. This class should implement a `set_form_definition_for_aiprovider_The typical directory layout for the Provider plugin, using OpenAI Provider as an example:
+ +```console +. +├── amd +│ ├── build +│ │ ├── modelchooser.min.js +│ │ └── modelchooser.min.js.map +│ └── src +│ └── modelchooser.js +├── classes +│ ├── abstract_processor.php +│ ├── aimodel +│ │ ├── gpt4o.php +│ │ └── o1.php +│ ├── form +│ │ ├── action_form.php +│ │ ├── action_generate_image_form.php +│ │ └── action_generate_text_form.php +│ ├── helper.php +│ ├── hook_listener.php +│ ├── privacy +│ │ └── provider.php +│ ├── process_generate_image.php +│ ├── process_generate_text.php +│ ├── process_summarise_text.php +│ └── provider.php +├── db +│ └── hooks.php +├── lang +│ └── en +│ └── aiprovider_openai.php +├── tests +│ ├── fixtures +│ │ ├── image_request_success.json +│ │ ├── test.jpg +│ │ └── text_request_success.json +│ ├── process_generate_image_test.php +│ ├── process_generate_text_test.php +│ ├── process_summarise_text_test.php +│ └── provider_test.php +└── version.php + +``` + +
+
+
+Some of the important files for the antivirus plugintype are described below. See the [common plugin files](../commonfiles) documentation for details of other files which may be useful in your plugin.
+
+### version.php
+
+View an example directory layout for the `antivirus_scanmyfile` plugin.
+ +```console + lib/antivirus/scanmyfile/ + |-- classes + | `-- scanner.php + |-- db + | `-- upgrade.php + |-- lang + | `-- en + | `-- antivirus_scanmyfile.php + |-- settings.php + |-- tests + | `-- scanner_test.php + `-- version.php +``` + +
+
+
+### settings.php
+
+
+
+
+
+export const settingsExample = `
+$settings->add(
+ new admin_setting_configcheckbox(
+ 'assignfeedback_file/default',
+ new lang_string('default', 'assignfeedback_file'),
+ new lang_string('default_help', 'assignfeedback_file'),
+ 0
+ )
+);
+`;
+
+export const settingsExtra = `
+All feedback plugins should include one setting named 'default' to indicate if the plugin should be enabled by default when creating a new assignment.
+`;
+
+View an example directory layout for the `assignfeedback_file` plugin.
+ +```console +mod/assign/feedback/file +├── backup +│ └── moodle2 +│ ├── backup_assignfeedback_file_subplugin.class.php +│ └── restore_assignfeedback_file_subplugin.class.php +├── classes +│ └── privacy +│ └── provider.php +├── db +│ ├── access.php +│ ├── install.php +│ ├── install.xml +│ └── upgrade.php +├── importzipform.php +├── importziplib.php +├── lang +│ └── en +│ └── assignfeedback_file.php +├── lib.php +├── locallib.php +├── settings.php +├── uploadzipform.php +└── version.php +``` + +
+
+
+### settings.php
+
+
+
+
+
+
+
+import settingsExample from '!!raw-loader!./_files/submission_settings.php';
+
+export const settingsExtra = `
+All submission plugins should include one setting named 'default' to indicate if the plugin should be enabled by default when creating a new assignment.
+`;
+
+View an example directory layout for the `assignfeedback_file` plugin.
+ +```console +mod/assign/submission/file +├── backup +│ └── moodle2 +│ ├── backup_assignsubmission_file_subplugin.class.php +│ └── restore_assignsubmission_file_subplugin.class.php +├── classes +│ ├── event +│ │ ├── assessable_uploaded.php +│ │ ├── submission_created.php +│ │ └── submission_updated.php +│ └── privacy +│ └── provider.php +├── db +│ ├── access.php +│ └── install.xml +├── lang +│ └── en +│ └── assignsubmission_file.php +├── lib.php +├── locallib.php +├── settings.php +└── version.php +``` + +"; +} +``` + +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() + +```php +public function delete_instance() { + global $DB; + // Will throw exception on failure + $DB->delete_records('assignsubmission_file', [ + 'assignment'=>$this->assignment->get_instance()->id, + ]); + + return true; +} +``` + +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. + +## 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. + +## Other features + +### Add calendar events + +
+
+
+Some of the important files for the Atto plugintype are described below. See the [common plugin files](../commonfiles) documentation for details of other files which may be useful in your plugin.
+
+### version.php
+
+
+
+View an example directory layout for the `atto_media` plugin.
+ +```console + lib/editor/atto/plugins/media + |-- db + | └-- upgrade.php + |-- lang + | └-- en + | └-- atto_media.php + |-- yui + | └-- src + | └-- button + | └-- atto_media.php + | ├── build.json + | ├── js + | │ └── button.js + | └── meta + | └── button.json + |-- settings.php + └-- version.php +``` + +
+
+
+Some of the important files for the format plugintype are described below. See the [common plugin files](../commonfiles) documentation for details of other files which may be useful in your plugin.
+
+### lang/en/availability_name.php
+
+import langExample from '!!raw-loader!./_examples/lang.php';
+import langDescription from './_examples/lang.md';
+
+View an example directory layout for the `availability_grouping` plugin.
+ +```console + availability/condition/grouping +├── classes +│ ├── condition.php +│ ├── frontend.php +├── lang +│ └── en +│ └── availability_grouping.php +├── version.php +└── yui + ├── build + │ └── moodle-availability_grouping-form + │ ├── moodle-availability_grouping-form-debug.js + │ ├── moodle-availability_grouping-form-min.js + │ └── moodle-availability_grouping-form.js + └── src + └── form + ├── build.json + ├── js + │ └── form.js + └── meta + └── form.json +``` + +
+
+
+### block_pluginname.php
+
+import BlockFile from '!!raw-loader!./_examples/block_pluginname.php';
+
+View an example directory layout for the `block_pluginname` plugin.
+ +```console + blocks/pluginname/ + |-- db + | `-- access.php + |-- lang + | `-- en + | `-- block_pluginname.php + |-- pix + | `-- icon.png + |-- block_pluginname.php + |-- edit_form.php (optional) + `-- version.php +``` + +
+
+
+## Block base class API methods
+
+All blocks must provide a main class that extends the core block class. However, there are two different types of blocks:
+
+- `block_base` - The default base class for content blocks.
+- `block_list` - For blocks that displays a list items.
+
+Depending on your plugin needs your main class in `blocks/pluginname/block_pluginname.php` must extend either `block_base` or `block_list`.
+
+### Block class attributes
+
+Once the block instance is created, there are several $this attributes that can be used:
+
+- `$this->config` The block instance configuration. By default it is an empty object but if the block has an [edit_form.php](#edit_formphp) file, it will be an object with the form data.
+- `$this->content` This variable holds all the actual content that is displayed inside each block. Valid values for it are either NULL or an object of class stdClass, which must have specific member variables depending on the extended block base class.
+- `$this->page` The page object that the block is being displayed on.
+- `$this->context` The context object that the block is being displayed in.
+- `$this->title` The title of the block.
+
+### init()
+
+The init method is called before the block is displayed. It is essential for all blocks, and its purpose is to give values to any class member variables that need instantiating. However, it is called before $this->config is set, if your plugin needs some configation value to define global attributes like the block title, it should be done in the specialization method.
+
+### specialization()
+
+This function is called on your subclass right after an instance is loaded. It is used to customize the title and other block attributes depending on the page type, context, configuration, etc.
+
+View pluginskel recipe
+
+
+import PluginskelRecipe from '!!raw-loader!./_examples/pluginskel_recipe.yaml';
+
+{PluginskelRecipe}
+
+
+
+
+
+### get_content(): string
+
+In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file) inside of the block_pluginname.php script.
+
+View example
+
+
+Example of a specialization method using the instance configuration.
+
+```php
+function specialization() {
+ if (isset($this->config->title)) {
+ $this->title = format_string($this->config->title, true, ['context' => $this->context]);
+ } else {
+ $this->title = get_string('newhtmlblock', 'block_html');
+ }
+}
+```
+
+
+
+
+
+:::note
+
+Even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.
+
+:::
+
+### hide_header(): bool
+
+Using this method each block instance can decide if the standard block header is shown or not. This method will be ignored in edit mode.
+
+View example
+
+
+```php
+public function instance_allow_multiple() {
+ return true;
+}
+```
+
+
+
+
+
+### html_attributes(): array
+
+The block base class can inject extra HTML attributes to the block wrapper. This is useful for example to add a class to the block wrapper when the block is being displayed in a specific context.
+
+By default, each block section in the page will use a standard `block` class and the specific `block_pluginname` class. However, if you want to add a class to the block wrapper, you can override html_attributes to alter those attrributes.
+
+View example
+
+
+```php
+public function hide_header() {
+ return true;
+}
+```
+
+
+
+
+
+This results in the block having all its normal HTML attributes, as inherited from the base block class, plus our additional class name. We can now use this class name to change the style of the block, add JavaScript events to it via YUI, and so on. And for one final elegant touch, we have not set the class to the hard-coded value "block_simplehtml", but instead used the Blocks/Appendix_A#name.28.29| name() method to make it dynamically match our block's name.
+
+### instance_config_save(): stdClass
+
+An optional method to modify the instance configuration before it is saved. See [add instance configuration settings](#add-instance-configuration-settings) section below for more information.
+
+### has_config(): bool
+
+An optional method to tell Moodle that the block has a global configuration settings form. See [enabling Global Configuration](#enabling-global-configuration) section below for more information.
+
+## Add instance configuration settings
+
+By default, block instances have no configuration settings. If you want to add some, you can add them by adding a few methods and classes to your block.
+
+### Create an edit_form.php file
+
+To have a configuration form, you need to add an [edit_form.php](#edit_formphp) file into your plugin. After defining the configuration, your block's base instance will have all your settings in its [$this->config attribute](#block-class-attributes). See the [edit_form.php section above](#edit_formphp) for an example.
+
+:::caution
+
+Note that $this->config is available in all block methods **except the init() one**. This is because init() is called immediately as the block is being created, with the purpose of setting things up. Use [specialization](#specialization) instead.
+
+:::
+
+:::note
+
+You cannot use the 'checkbox' element in the form (once set it will stay set). You must use advcheckbox instead.
+
+:::
+
+### Optional instance_config_save method
+
+By default, all config_* settings will be stored in the `block_instances` table. The complete form data will be encoded in base64 before storing it in the `configdata` field. Every time a block instance is initialized all that data will be decoded in the [$this->config attribute](#block-class-attributes).
+
+However, for some cases like the Atto HTML editor, you may want to store them in the database instead, or to alter the config data before storing it. In that case you can create a instance_config_save method.
+
+View example
+
+
+```php
+public function html_attributes() {
+ // Get default values.
+ $attributes = parent::html_attributes();
+ // Append our class to class attribute.
+ $attributes['class'] .= ' block_'. $this->name();
+ return $attributes;
+}
+```
+
+
+
+
+
+## Add global settings to the block plugin
+
+Apart from the specific block instance configuration, the block plugin can use global settings to customize its behavior. Those settings can only be set in the site administration and are a great way to customize the behavior of all blocks on a site.
+
+:::note
+
+Global settings are not part of the block instance and should be accessed via the global get_config method. For example:
+
+```php
+$settingvalue = get_config('block_pluginname', 'settingname');
+```
+
+:::
+
+### create a settings.php file
+
+Implementing such configuration for our block is quite similar to implementing the [instance configuration](#add-instance-configuration-settings). To enable global configuration for the block, your plugin should contain **/blocks/simplehtml/settings.php** file. This file will populate the global admin form with form field definitions for each setting. See [Common files: settings.php](../commonfiles#settingsphp) for more information.
+
+### Enabling Global Configuration
+
+While in other Moodle pulgins the existence of a settings.php is enough to enable global configuration, for the blocks plugins it is mandatory to override the has_config method in the base class.
+
+View example
+
+
+```php title="Example of adding data before storing it
+public function instance_config_save($data,$nolongerused =false) {
+ // Example of add new data.
+ $data->somenewattribute = 'Some new value';
+
+ // Example of alter the current data.
+ $data->text = 'Some new text';
+
+ // Call the parent method to the data inside block_instance.configdata.
+ return parent::instance_config_save($data,$nolongerused);
+}
+```
+
+
+
+
+
+## Limit the block to specific contexts
+
+Some blocks are useful in some circumstances, but not in others. An example of this would be the "Social Activities" block, which is useful in courses with the "social" course format, but not courses with the "weeks" format. Moodle allows us to declare in which pages a block is available on. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.
+
+Each page in Moodle can define it's own page type name. However, there are some conventions:
+
+- `all` value is used as a catch-all option. This means that if a block returns `['all' => true]` it can be used in any kind of page.
+- `site-index` - Moodle frontpage.
+- `course-view` - Course page, independent from the course format.
+- `course-view-FORMATNAME` - Course page, with the "FORMATNAME" course format. For example, course-view-weeks is for courses with weeks format.
+- `mod` - Any activity page, independent from the module.
+- `mod-MODNAME-view` - Activity page, with the "MODNAME" activity. For example, mod-forum-view is for forums.
+- `my` - The Moodle dashboard page.
+- `admin` - Any administration page.
+
+View example
+
+
+```php"
+function has_config() {
+ return true;
+}
+```
+
+
+
+
diff --git a/versioned_docs/version-5.1/apis/plugintypes/communication/index.md b/versioned_docs/version-5.1/apis/plugintypes/communication/index.md
new file mode 100644
index 0000000000..80b89180dd
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/communication/index.md
@@ -0,0 +1,158 @@
+---
+title: Communication plugin
+tags:
+ - communication
+ - provider
+ - Communication provider
+ - Communication room
+ - Communication service
+ - Chat
+documentationDraft: true
+---
+
+Communication plugin allows you to create a communication provider plugin, which can be added as a part of course or any other instances.
+For example, if you want to create a new communication room and add users to that room when a new course or instance is created, you can
+create a new communication plugin and or use the existing ones and when a instance is created, updated or deleted, the communication api
+will align those changes in the provider plugin asynchronously using a scheduled task.
+
+import {
+Lang,
+} from '../../_files';
+
+## File structure
+
+Communication plugins are located in the /communication/provider directory. A plugin should not include any custom files outside its own
+plugin folder.
+
+Each plugin is in a separate subdirectory and consists of a number of _mandatory files_ and any other files the developer is going to use.
+
+:::important
+
+Some important files are described below. See the [common plugin files](../../commonfiles/index.mdx) documentation for details of other
+files which may be useful in your plugin.
+
+:::
+
+View example
+
+
+```php
+public function applicable_formats() {
+ return [
+ 'admin' => false,
+ 'site-index' => false,
+ 'course-view' => true,
+ 'mod' => true,
+ 'my' => false
+ ];
+}
+```
+
+
+
+
+
+:::info
+
+You will notice that there are a couple of classes named as example as a prefix, these are feature classes and can be named however
+you like. These are feature classes which will be defined from the communication_feature.php from the plugin.
+
+:::
+
+## Key files
+
+There are a number of key files within the plugin, described below.
+
+### communication_feature.php
+
+Each plugin must implement this class and should have the exact class name. The core communication api will pick the features and actions from this class. There is no strict rule
+on which interfaces should be implemented, plugins can choose which features they support and implement accordingly. Exception is the `communication_provider` interface which
+is mandatory for all the plugins. Check below for more details on the interfaces.
+
+```php
+class communication_feature implements
+ \core_communication\communication_provider,
+ \core_communication\user_provider,
+ \core_communication\room_chat_provider,
+ \core_communication\room_user_provider {
+
+ // All the methods from interfaces should live here.
+
+}
+```
+
+## Interfaces
+
+### communication_provider
+
+This is the base communication provider interface. This interface should be used to declare the support for the instantiation method for communication providers.
+Every provider plugin must implement this interface as a bare minimum. This interface will have the following methods.
+
+#### load_for_instance()
+
+This method will have the base communication processor(core_communication\processor) object which will allow loading the communication provider for the communication api.
+
+### user_provider
+
+This is the user provider interface. This interface should be used to declare the support for the for user creation for a provider. For example, Matrix allows creation of users
+via API and the `communication_matrix` plugin can support the creation of users in Matrix, in that case, `communication_matrix` plugin should implement this interface. Some APIs might
+not need to create user as they might have been created in a different way, in that case this interface can be excluded. This interface will have the following methods.
+
+#### create_members()
+
+All the necessary code and API calls to create members for the communication room should live here.
+
+### room_chat_provider
+
+This interface will define the features for creating a room. For example, if a communication provider allows creating a room via API, this interface should be implemented.
+Let's look at the methods of this interface to get a better idea.
+
+#### create_chat_room()
+
+#### update_chat_room()
+
+All the necessary actions to create/update a provider room should live here. It is highly recommended to add necessary checking to compare the
+data passed and previous data to ensure something is changed and an update is required to make sure no unnecessary api calls are made. A bool
+value should be returned to indicate if the room is created or updated or something went wrong.
+
+#### delete_chat_room()
+
+!!Danger zone!! Any deletion or related action for the communication room should live here. Please be-careful with your actions here. A bool
+value should be returned to indicate if the room is deleted or something went wrong.
+
+#### generate_room_url()
+
+Generate a room url according to the room information, web client url or any other required information. This is an important one to allow users access the room from the UI.
+Course has an icon to access the room if a room is created for the course, this method will be used to generate the url for the room.
+
+### room_user_provider
+
+This interface will define the features for adding/removing/updating members to the room. Room members should be added when a user is enrolled or a role changes. If a provider
+allows addition of users to a room via API, this interface should be implemented. Let's look at the methods of this class to get a better idea.
+
+#### add_members_to_room()
+
+All the necessary actions to add members to a room should live here. The array of user ids must be passed here.
+
+#### update_room_membership()
+
+Updating the membership might be necessary in some cases where a user is capability changed, this method will come into play in those cases.
+
+#### remove_members_from_room()
+
+All the necessary actions to remove members from a room should live here. The array of user ids must be passed here.
+
+### synchronise_provider
+
+Communication API has a scheduled task `core_communication\task\synchronise_providers_task` which will synchronise the data from the communication provider to the current Moodle
+instance. For example, it can compare the users in the communication room and users enrolled in a course and add/remove users accordingly. The scheduled task runs and adds an
+ad-hoc task for each instance where the provider implements this interface. This feature will help keep the data on-sync between the provider and Moodle.
+
+#### synchronise_room_members()
+
+All the necessary code to synchronise the room members should live here.
+
+:::info
+
+For a real plugin example, please look at the [Matrix plugin](https://github.com/moodle/moodle/tree/main/communication/provider/matrix).
+
+:::
diff --git a/versioned_docs/version-5.1/apis/plugintypes/customfield/_files/data_controller.php b/versioned_docs/version-5.1/apis/plugintypes/customfield/_files/data_controller.php
new file mode 100644
index 0000000000..8e2d30416a
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/customfield/_files/data_controller.php
@@ -0,0 +1,53 @@
+namespace customfield_checkbox;
+
+class data_controller extends \core_customfield\data_controller {
+
+ /**
+ * Return the name of the field where the information is stored
+ * @return string
+ */
+ public function datafield(): string {
+ return 'intvalue';
+ }
+
+ /**
+ * Add fields for editing a checkbox field.
+ *
+ * @param \MoodleQuickForm $mform
+ */
+ public function instance_form_definition(\MoodleQuickForm $mform) {
+ $field = $this->get_field();
+ $config = $field->get('configdata');
+ $elementname = $this->get_form_element_name();
+
+ // If checkbox is required (i.e. "agree to terms") then use 'checkbox' form element.
+ // The advcheckbox element cannot be used for required fields because advcheckbox elements always provide a value.
+ $isrequired = $field->get_configdata_property('required');
+ $mform->addElement($isrequired ? 'checkbox' : 'advcheckbox', $elementname, $this->get_field()->get_formatted_name());
+ $mform->setDefault($elementname, $config['checkbydefault']);
+ $mform->setType($elementname, PARAM_BOOL);
+
+ if ($isrequired) {
+ $mform->addRule($elementname, null, 'required', null, 'client');
+ }
+ }
+
+ /**
+ * Returns the default value as it would be stored in the database (not in human-readable format).
+ *
+ * @return mixed
+ */
+ public function get_default_value() {
+ return $this->get_field()->get_configdata_property('checkbydefault') ? 1 : 0;
+ }
+
+ /**
+ * Returns value in a human-readable format
+ *
+ * @return mixed|null value or null if empty
+ */
+ public function export_value() {
+ $value = $this->get_value();
+ return $value ? get_string('yes') : get_string('no');
+ }
+}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/customfield/_files/data_controller.tsx b/versioned_docs/version-5.1/apis/plugintypes/customfield/_files/data_controller.tsx
new file mode 100644
index 0000000000..abc3371585
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/customfield/_files/data_controller.tsx
@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) Moodle Pty Ltd.
+ *
+ * Moodle is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Moodle is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Moodle. If not, see The directory layout for the `communication` plugin.
+ +```console +communication/provider/example +├── classes +│ ├── communication_feature.php +│ └── privacy +│ └── provider.php +├── lang +│ └── en +│ └── communication_example.php +├── settings.php +└── version.php +``` + +
+
+
+A custom field plugin requires two _controller_ classes:
+
+- a _field_ controller, which describes the field itself; and
+- a _data_ controller, which describes with interface within the context of the instance (i.e. course).
+
+### Field Controller
+
+The field controller defines the available configuration options that an administrator can select within the user interface to configure the field.
+
+Examples might include the prompt to show alongside the custom field element, and whether the element is required.
+
+:::note Class naming
+
+The class must be named `field_controller` within your plugin's namespace (for example `customfield_myfield`) and must extend the `\core_customfield\field_controller` class.
+
+:::
+
+
+
+
+import fieldExample from '!!raw-loader!./_files/field_controller.php';
+
+View an example directory layout for the `customfield_checkbox` plugin.
+ +```console +customfield/field/checkbox +├── classes +│ ├── data_controller.php +│ ├── field_controller.php +│ └── privacy +│ └── provider.php +├── lang +│ └── en +│ └── customfield_checkbox.php +└── version.php +``` + +
+
+
+Some of the important files for the format plugintype are described below. See the [common plugin files](../commonfiles) documentation for details of other files which may be useful in your plugin.
+
+### lib.php
+
+import LibExample from '!!raw-loader!./_examples/lib.php';
+
+View an example directory layout for the `enrol_pluginname` plugin.
+ +```console + enrol/pluginname/ + |-- db + | `-- access.php + |-- lang + | `-- en + | `-- enrol_pluginname.php + `-- lib.php + `-- version.php +``` + +
+
+
+### enrol_plugin::allow_unenrol(): bool
+
+This method returns true if other code allowed to unenrol everybody from one instance. This method is used on course reset and manual unenrol.
+
+:::note
+
+The unenrol action will allow resetif all following conditions are met:
+
+- The method `enrol_plugin::allow_unenrol()` returns true
+- The current user has the `enrol/pluginname:unenrol` capability.
+
+:::
+
+View example
+
+
+```php
+/**
+ * Gets an array of the user enrolment actions
+ *
+ * @param course_enrolment_manager $manager
+ * @param stdClass $userenrolment
+ * @return array An array of user_enrolment_actions
+ */
+public function get_user_enrolment_actions(course_enrolment_manager $manager, $userenrolment) {
+ $actions = parent::get_user_enrolment_actions($manager, $userenrolment);
+ $context = $manager->get_context();
+ $instance = $userenrolment->enrolmentinstance;
+ $params = $manager->get_moodlepage()->url->params();
+ $params['ue'] = $userenrolment->id;
+
+ // Edit enrolment action.
+ if ($this->allow_manage($instance) && has_capability("enrol/{$instance->enrol}:something", $context)) {
+ $title = get_string('newaction', 'enrol');
+ $icon = new pix_icon('t/edit', '');
+ $url = new moodle_url('/enrol/pluginname/something.php', $params);
+ $actions[] = new user_enrolment_action($icon, $title, $url);
+ }
+
+ return $actions;
+}
+```
+
+
+
+
+
+### enrol_plugin::allow_unenrol_user(): bool
+
+This method returns true if other code allowed to unenrol a specific user from one instance.
+
+:::tip
+
+If `allow_unenrol_user` is not overridden, the default behaviour is to call `allow_unenrol()` method.
+
+:::
+
+:::note
+
+The unenrol action will be displayed if all following conditions are met:
+
+- The method `enrol_plugin::allow_unenrol_user()` returns true
+- The current user has the `enrol/pluginname:unenrol` capability.
+
+:::
+
+View example
+
+
+```php
+public function allow_unenrol(stdClass $instance) {
+ // Add any extra validation here.
+ return true;
+}
+```
+
+
+
+
+
+It is quite common in enrolment plugins to allow unenrol only if the user enrolment is suspended (for example: *enrol_database*, *enrol_flatfile*, *enrol_meta*).
+
+View example
+
+
+```php
+public function allow_unenrol_user(stdClass $instance, stdClass $userenrolment) {
+ // Add any extra validation here.
+ return true;
+}
+
+```
+
+
+
+
+
+### enrol_plugin::allow_enrol(): bool
+
+Define if the enrol plugin is compatible with manual enrolments.
+
+:::note
+
+The edit manual enrolment action will be displayed if if all following conditions are met:
+
+- The method `enrol_plugin::allow_enrol()` returns true
+- The current user has the `enrol/pluginname:enrol` capability.
+
+:::
+
+View suspended enrolment example
+
+
+```php
+public function allow_unenrol_user(stdClass $instance, stdClass $userenrolment) {
+ if ($userenrolment->status == ENROL_USER_SUSPENDED) {
+ return true;
+ }
+ return false;
+}
+```
+
+
+
+
+
+### enrol_plugin::enrol_user()
+
+This method is the plugin enrolment hook. It will be called when user is enrolled in the course using one of the plugin instances. It is used to alter the enrolment data (for example altering the dates or the role) and also to throw exceptions if some external condions are not met.
+
+View example
+
+
+```php
+public function allow_enrol(stdClass $instance) {
+ // Add any extra validation here.
+ return true;
+}
+```
+
+
+
+
+
+### enrol_plugin:allow_manage(): bool
+
+Return true if plugin allows manual modification of user enrolments from other code. False is usually returned from plugins that synchronise data with external systems, otherwise the manual changes would be reverted immediately upon synchronisation.
+
+:::note
+
+The edit enrolment action in the participants list will be displayed if if all following conditions are met:
+
+- The method `allow_manage` returns true
+- The current user has the `enrol/pluginname:manage` capability.
+
+:::
+
+View example
+
+
+```php
+/**
+ * Enrol a user using a given enrolment instance.
+ *
+ * @param stdClass $instance the plugin instance
+ * @param int $userid the user id
+ * @param int $roleid the role id
+ * @param int $timestart enrolment start timestamp
+ * @param int $timeend enrolment end timestamp
+ * @param int $status default to ENROL_USER_ACTIVE for new enrolments, no change by default in updates
+ * @param bool $recovergrades restore grade history
+ */
+public function enrol_user(
+ stdClass $instance,
+ $userid,
+ $roleid = null,
+ $timestart = 0,
+ $timeend = 0,
+ $status = null,
+ $recovergrades = null
+) {
+ // Add validations here.
+
+ parent::enrol_user(
+ $instance,
+ $userid,
+ $roleid,
+ $timestart,
+ $timeend,
+ $status,
+ $recovergrades
+ );
+}
+```
+
+
+
+
+
+### enrol_plugin::roles_protected(): bool
+
+Enrolment plugins can protect roles from being modified by any other plugin. Returning false will allow users to remove all roles assigned by this plugin. By default, this method returns true.
+
+:::
+
+View example
+
+
+```php
+public function allow_manage(stdClass $instance) {
+ // Add any extra validation here.
+ return true;
+}
+```
+
+
+
+
+
+### enrol_plugin:find_instance(): stdClass {#enrol_pluginfind_instance-stdclass}
+
+Returns enrolment instance in a given course matching provided data. If enrol plugin implements this method, then it is supported
+ in CSV course upload.
+
+:::note
+
+So far following enrol plugins implement this method: *enrol_manual*, *enrol_self*, *enrol_guest*, *enrol_cohort*.
+ Method must be capable to uniquely identify instance in a course using provided data in order to implement this method. For example, *enrol_cohort* uses
+ `cohortID` together with `roleID` to identify instance. For some methods (like *enrol_lti* or *enrol_payment*) it is not possible
+ to uniquely identify instance in a course using provided data, so such methods will not be supported in CSV course upload.
+
+The only exception is *enrol_self* - although it is not possible to uniquely identify enrolment instance in a course using provided data, it is still supported in CSV course upload. For *enrol_self* method `find_instance()` returns the first available enrolment instance in a course.
+
+:::
+
+View example
+
+
+```php
+public function roles_protected() {
+ // Add any extra validation here if necessary.
+ return false;
+}
+```
+
+
+
+
+
+## Standard Editing UI
+
+Moodle participants page has a standard editing UI for manual enrolments. To integrate a plugin into the start UI you need to implement the following methods:
+
+- `enrol_plugin::use_standard_editing_ui()`
+- `enrol_plugin::edit_instance_form()`
+- `enrol_plugin::edit_instance_validation()`
+- `enrol_plugin::can_add_instance()`
+- `enrol_plugin::add_instance()`
+
+This means that the following functions from the plugin will be called to build the add/edit form, perform validation of the data and add standard navigation links to the manage enrolments page and course navigation.
+
+View example
+
+
+```php
+public function find_instance(array $enrolmentdata, int $courseid) : ?stdClass {
+ global $DB;
+ $instances = enrol_get_instances($courseid, false);
+
+ $instance = null;
+ if (isset($enrolmentdata['cohortidnumber']) && isset($enrolmentdata['role'])) {
+ $cohortid = $DB->get_field('cohort', 'id', ['idnumber' => $enrolmentdata['cohortidnumber']]);
+ $roleid = $DB->get_field('role', 'id', ['shortname' => $enrolmentdata['role']]);
+ if ($cohortid && $roleid) {
+ foreach ($instances as $i) {
+ if ($i->enrol == 'cohort' && $i->customint1 == $cohortid && $i->roleid == $roleid) {
+ $instance = $i;
+ break;
+ }
+ }
+ }
+ }
+ return $instance;
+}
+```
+
+
+
+
+
+## Sending a welcome email
+
+Some enrol methods has the support for sending welcome mesages to users. To grant the enrol messages are consistent acorrs enrolments methods, the enrol API provides the `enrol_send_welcome_email_options` function. This method returns a list of all possible options for sending welcome email when the user enrol in a course and each option has a respective constant defined on **enrollib.php**:
+
+```php
+define('ENROL_DO_NOT_SEND_EMAIL', 0); // Do not send the welcome email.
+define('ENROL_SEND_EMAIL_FROM_COURSE_CONTACT', 1); // Send welcome email from course contact.
+define('ENROL_SEND_EMAIL_FROM_KEY_HOLDER', 2); // Send welcome email from course key holder.
+define('ENROL_SEND_EMAIL_FROM_NOREPLY', 3); // Send welcome email from no reply.
+```
+
+View example
+
+
+import UiLib from '!!raw-loader!./_examples/ui_lib.php';
+
+{UiLib}
+
+
+
+
+
+## See also
+
+- [Enrolment API](../../subsystems/enrol.md)
diff --git a/versioned_docs/version-5.1/apis/plugintypes/fileconverter/_files/converter.md b/versioned_docs/version-5.1/apis/plugintypes/fileconverter/_files/converter.md
new file mode 100644
index 0000000000..da4cf2ea22
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/fileconverter/_files/converter.md
@@ -0,0 +1,6 @@
+
+
+
+The `classes/converter.php` class must be defined in the correct namespace for your plugin, and must implement the `\core_files\converter_interface` interface.
+
+It is responsible for converting files
diff --git a/versioned_docs/version-5.1/apis/plugintypes/fileconverter/_files/converter.tsx b/versioned_docs/version-5.1/apis/plugintypes/fileconverter/_files/converter.tsx
new file mode 100644
index 0000000000..a1a3702eac
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/fileconverter/_files/converter.tsx
@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) Moodle Pty Ltd.
+ *
+ * Moodle is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Moodle is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Moodle. If not, see View example
+
+
+import MessageLib from '!!raw-loader!./_examples/message_lib.php';
+
+{MessageLib}
+
+
+
+
+
+Some of the important files for the fileconverter plugintype are described below. See the [common plugin files](../commonfiles) documentation for details of other files which may be useful in your plugin.
+
+### Converter class
+
+import Converter from './_files/converter';
+
+View an example directory layout for the `fileconverter_unoconv` plugin.
+ +```console +files/converter/unoconv +├── classes +│ ├── converter.php +│ └── privacy +│ └── provider.php +├── lang +│ └── en +│ └── fileconverter_unoconv.php +├── settings.php +└── version.php +``` + +
+
+
+Some of the important files for the filter plugintype are described below. See the [common plugin files](../commonfiles) documentation for details of other files which may be useful in your plugin.
+
+### classes/text_filter.php
+
+import Filter from '!!raw-loader!./_examples/filter.php';
+
+View an example directory layout for the `filter_pluginname` plugin.
+ +```console + filter/pluginname/ + |-- lang + | `-- en + | `-- filter_pluginname.php + |-- classes + | `-- text_filter.php + `-- version.php +``` + +
+
+
+## Local configuration
+
+Filters can use different configuration depending on the context in which they are called. For example, the glossary filter can be configured such that when displayed in Forum A it only links words from a particular glossary, while in Forum B it links words from a different glossary..
+
+To support this behaviour, a filter plugin must provide a `filterlocalsettings.php` file which defines a Moodle form which subclasses the `filter_local_settings_form` class. In addition to the standard formslib methods, you must also define a `save_changes` method.
+
+View example
+
+
+```php
+/**
+ * Example of a filter that uses links in some way.
+ */
+public function filter($text, array $options = []) {
+
+ if (!is_string($text) or empty($text)) {
+ // Non-string data can not be filtered anyway.
+ return $text;
+ }
+
+ if (stripos($text, '') === false) {
+ // Performance shortcut - if there is no tag, nothing can match.
+ return $text;
+ }
+
+ // Here we can perform some more complex operations with the
+ // links in the text.
+}
+```
+
+
+
+
+
+All the local configurations can be accessed in the main filter class in the `$this->localconfig` property.
+
+View example
+
+
+```php title="filterlocalsettings.php"
+class pluginfile_filter_local_settings_form extends \core_filters\form\local_settings_form {
+ protected function definition_inner(\MoodleQuickForm $mform) {
+ $mform->addElement(
+ 'text',
+ 'word',
+ get_string('word', 'filter_helloworld'),
+ ['size' => 20]
+ );
+ $mform->setType('word', PARAM_NOTAGS);
+ }
+}
+```
+
+
+
+
+
+## Filtering dynamic content
+
+It is possible that page content is loaded by ajax after the page is loaded. In certain filter types (for example MathJax) JavaScript is required to be run on the output of the filter in order to do the final markup. For these types of filters, a JavaScript event is triggered when new content is added to the page (the content will have already been processed by the filter in php). The JavaScript for a filter can listen for these event notifications and reprocess the affected dom nodes.
+
+The content updated event is registered in the `core_filters/events` module and can be imported as:
+
+```js
+import {eventTypes} from 'core_filters/events';
+
+document.addEventListener(eventTypes.filterContentUpdated, eventHandler);
+```
+
+View example
+
+
+```php title="filter/pluginname/classes/text_filter.php"
+localconfig['word'] ?? 'default';
+ return str_replace($search, "Hello $search!", $text);
+ }
+}
+```
+
+
+
+
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/format.php b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/format.php
new file mode 100644
index 0000000000..3683a8ca54
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/format.php
@@ -0,0 +1,27 @@
+defined('MOODLE_INTERNAL') || die();
+
+require_once($CFG->libdir . '/filelib.php');
+require_once($CFG->libdir . '/completionlib.php');
+
+// Retrieve course format option fields and add them to the $course object.
+$format = core_courseformat\base::instance($course);
+$course = $format->get_course();
+$context = context_course::instance($course->id);
+
+// Add any extra logic here.
+
+// Make sure section 0 is created.
+course_create_sections_if_missing($course, 0);
+
+$renderer = $format->get_renderer($PAGE);
+
+// Setup the format base instance.
+if (!empty($displaysection)) {
+$format->set_section_number($displaysection);
+}
+// Output course content.
+$outputclass = $format->get_output_classname('content');
+$widget = new $outputclass($format);
+echo $renderer->render($widget);
+
+// Include any format js module here using $PAGE->requires->js.
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/format_lang.php b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/format_lang.php
new file mode 100644
index 0000000000..e5183221b2
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/format_lang.php
@@ -0,0 +1,12 @@
+
+$string['addsections'] = 'Add section';
+$string['currentsection'] = 'This section';
+$string['deletesection'] = 'Delete section';
+$string['editsection'] = 'Edit section';
+$string['editsectionname'] = 'Edit section name';
+$string['hidefromothers'] = 'Hide section';
+$string['newsectionname'] = 'New name for section {$a}';
+$string['pluginname'] = 'pluginname format';
+$string['privacy:metadata'] = 'The Sample format plugin does not store any personal data.';
+$string['sectionname'] = 'Section';
+$string['showfromothers'] = 'Show section';
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/lib.php b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/lib.php
new file mode 100644
index 0000000000..3c2e9152ea
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/lib.php
@@ -0,0 +1,104 @@
+
+class format_pluginname extends core_courseformat\base {
+
+ /**
+ * Returns true if this course format uses sections.
+ *
+ * @return bool
+ */
+ public function uses_sections() {
+ return true;
+ }
+
+ public function uses_indentation(): bool {
+ return false;
+ }
+
+ public function uses_course_index() {
+ return true;
+ }
+
+ /**
+ * Returns the information about the ajax support in the given source format.
+ *
+ * The returned object's property (boolean)capable indicates that
+ * the course format supports Moodle course ajax features.
+ *
+ * @return stdClass
+ */
+ public function supports_ajax() {
+ $ajaxsupport = new stdClass();
+ $ajaxsupport->capable = true;
+ return $ajaxsupport;
+ }
+
+ public function supports_components() {
+ return true;
+ }
+
+ /**
+ * Whether this format allows to delete sections.
+ *
+ * Do not call this function directly, instead use {@link course_can_delete_section()}
+ *
+ * @param int|stdClass|section_info $section
+ * @return bool
+ */
+ public function can_delete_section($section) {
+ return true;
+ }
+
+ /**
+ * Indicates whether the course format supports the creation of a news forum.
+ *
+ * @return bool
+ */
+ public function supports_news() {
+ return true;
+ }
+
+ /**
+ * Returns the display name of the given section that the course prefers.
+ *
+ * This method is required for inplace section name editor.
+ *
+ * @param int|stdClass $section Section object from database or just field section.section
+ * @return string Display name that the course format prefers, e.g. "Topic 2"
+ */
+ public function get_section_name($section) {
+ $section = $this->get_section($section);
+ if ((string)$section->name !== '') {
+ return format_string(
+ $section->name,
+ true,
+ ['context' => context_course::instance($this->courseid)]
+ );
+ } else {
+ return $this->get_default_section_name($section);
+ }
+ }
+}
+
+/**
+ * Implements callback inplace_editable() allowing to edit values in-place.
+ *
+ * This method is required for inplace section name editor.
+ *
+ * @param string $itemtype
+ * @param int $itemid
+ * @param mixed $newvalue
+ * @return inplace_editable
+ */
+function format_pluginname_inplace_editable($itemtype, $itemid, $newvalue) {
+ global $DB, $CFG;
+ require_once($CFG->dirroot . '/course/lib.php');
+ if ($itemtype === 'sectionname' || $itemtype === 'sectionnamenl') {
+ $section = $DB->get_record_sql(
+ 'SELECT s.* FROM {course_sections} s JOIN {course} c ON s.course = c.id WHERE s.id = ? AND c.format = ?',
+ [$itemid, 'pluginname'],
+ MUST_EXIST
+ );
+ $format = core_courseformat\base::instance($section->course);
+ return $format->inplace_editable_update_section_name($section, $itemtype, $newvalue);
+ }
+}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/lib_components.php b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/lib_components.php
new file mode 100644
index 0000000000..32d9a1a0ce
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/lib_components.php
@@ -0,0 +1,8 @@
+class format_PLUGINNAME extends core_courseformat\base {
+
+ // More methods can be added here.
+
+ public function supports_components() {
+ return true;
+ }
+}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/lib_course_index.php b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/lib_course_index.php
new file mode 100644
index 0000000000..dbb6109248
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/lib_course_index.php
@@ -0,0 +1,8 @@
+class format_PLUGINNAME extends core_courseformat\base {
+
+ // More methods can be added here.
+
+ public function uses_course_index() {
+ return true;
+ }
+}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/cmitem.mustache b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/cmitem.mustache
new file mode 100644
index 0000000000..7b0d80da79
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/cmitem.mustache
@@ -0,0 +1,8 @@
+{{!
+ Include the core content/section/cmitem template.
+}}
+{{< core_courseformat/local/content/section/cmitem }}
+ {{!
+ Add any cm item blocks override here.
+ }}
+{{/ core_courseformat/local/content/section/cmitem }}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/cmitem.php b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/cmitem.php
new file mode 100644
index 0000000000..670db67e0c
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/cmitem.php
@@ -0,0 +1,16 @@
+
+namespace format_pluginname\output\courseformat\content\section;
+
+use core_courseformat\output\local\content\section\cmitem as cmitem_base;
+
+class cmitem extends cmitem_base {
+
+ /**
+ * Returns the output class template path.
+ *
+ * This method redirects the default template when the section activity item is rendered.
+ */
+ public function get_template_name(\renderer_base $renderer): string {
+ return 'format_pluginname/local/content/section/cmitem';
+ }
+}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/content.mustache b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/content.mustache
new file mode 100644
index 0000000000..377189df1c
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/content.mustache
@@ -0,0 +1,14 @@
+{{!
+ Include the core content template.
+ This is the top template for a course.
+}}
+{{< core_courseformat/local/content }}
+ {{!
+ Add any general structure blocks override here.
+ }}
+
+ {{! Mandatory the content/section block. }}
+ {{$ core_courseformat/local/content/section }}
+ {{> format_pluginname/local/content/section }}
+ {{/ core_courseformat/local/content/section }}
+{{/ core_courseformat/local/content }}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/content.php b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/content.php
new file mode 100644
index 0000000000..6432366ea0
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/content.php
@@ -0,0 +1,16 @@
+
+namespace format_pluginname\output\courseformat;
+
+use core_courseformat\output\local\content as content_base;
+
+class content extends content_base {
+
+ /**
+ * Returns the output class template path.
+ *
+ * This method redirects the default template when the course content is rendered.
+ */
+ public function get_template_name(\renderer_base $renderer): string {
+ return 'format_pluginname/local/content';
+ }
+}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/renderer.php b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/renderer.php
new file mode 100644
index 0000000000..e9821f2314
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/renderer.php
@@ -0,0 +1,9 @@
+
+namespace format_pluginname\output;
+
+use core_courseformat\output\section_renderer;
+use moodle_page;
+
+class renderer extends section_renderer {
+ // Your renderer methods goes here.
+}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/section.mustache b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/section.mustache
new file mode 100644
index 0000000000..3225b76066
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/section.mustache
@@ -0,0 +1,12 @@
+{{!
+ Include the core content/section template.
+}}
+{{< core_courseformat/local/content/section }}
+ {{!
+ Add any section blocks override here.
+ }}
+ {{! Mandatory cmitem override }}
+ {{$ core_courseformat/local/content/section/cmitem }}
+ {{> format_pluginname/local/content/section/cmitem }}
+ {{/ core_courseformat/local/content/section/cmitem }}
+{{/ core_courseformat/local/content/section }}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/section.php b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/section.php
new file mode 100644
index 0000000000..d1d8e4c64f
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/output/section.php
@@ -0,0 +1,16 @@
+
+namespace format_pluginname\output\courseformat\content;
+
+use core_courseformat\output\local\content\section as section_base;
+
+class section extends section_base {
+
+ /**
+ * Returns the output class template path.
+ *
+ * This method redirects the default template when the course section is rendered.
+ */
+ public function get_template_name(\renderer_base $renderer): string {
+ return 'format_pluginname/local/content/section';
+ }
+}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/format/_examples/pluginskel_recipe.yaml b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/pluginskel_recipe.yaml
new file mode 100644
index 0000000000..a57d181216
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/format/_examples/pluginskel_recipe.yaml
@@ -0,0 +1,84 @@
+## This is an example recipe file that you can use as a template for your own plugins.
+## See the list of all files it would generate:
+##
+## php generate.php example.yaml --list-files
+##
+## View a particular file contents without actually writing it to the disk:
+##
+## php generate.php example.yaml --file=version.php
+##
+## To see the full list of options, run:
+##
+## php generate.php --help
+##
+---
+## Frankenstyle component name.
+component: format_pluginname
+
+## Human readable name of the plugin.
+name: Example pluginname format
+
+## Human readable release number.
+release: "0.1.0"
+
+## Plugin version number, e.g. 2016062100. Will be set to current date if left empty.
+#version: 2016121200
+
+## Required Moodle version, e.g. 2015051100 or "2.9".
+requires: "4.0"
+
+## Plugin maturity level. Possible options are MATURIY_ALPHA, MATURITY_BETA,
+## MATURITY_RC or MATURIY_STABLE.
+maturity: MATURITY_BETA
+
+## Copyright holder(s) of the generated files and classes.
+copyright: YOURNAME View example
+
+
+import DynamicContent from '!!raw-loader!./_examples/dynamic.js';
+
+{DynamicContent}
+
+
+
+
+
+Some of the important files for the format plugintype are described below. See the [common plugin files](../commonfiles) documentation for details of other files which may be useful in your plugin.
+
+### format.php
+
+import Format from '!!raw-loader!./_examples/format.php';
+
+View an example directory layout for the `format_pluginname` plugin.
+ +```console + course/format/pluginname/ + |-- classes + | `-- output + | `-- courseformat + | `-- (Overridden outputs) + | `-- renderer.php + |-- db + | `-- access.php + |-- lang + | `-- en + | `-- format_pluginname.php + |-- format.php + |-- lib.php + `-- version.php +``` + +
+
+
+### Manual option: copy the code from an existing code
+
+However, if for some reason you cannot use the latest version of tool_pluginskel, you can copy the code from the topics or weeks formats. Once you do the copy you should:
+
+1. Copy the folder containing the format files.
+2. Rename the folder to the new name. Course format names cannot exceed 21 characters.
+3. Rename language files in course/format/pluginname/lang/
+4. Change `$string['pluginname']` in course/format/pluginname/lang/en/format_pluginname.php to the new name.
+5. Rename class name in lib.php to format_pluginname.
+6. Search and replace other occurrences of the old format name, for example in renderer, capabilities names, settings, JavaScript libraries, etc.
+7. The new format is ready for modification.
+8. After modifying the code, check it with the Code checker.
+
+## Upgrading format to the next Moodle version
+
+Read the files course/format/upgrade.txt, lib/upgrade.txt, and also upgrade.txt of the core APIs that you use in your course format plugin and make changes according to them. When testing don't forget to enable Developer debugging level and error display (Settings->Developer->Debugging).
+
+In case your plugin is a Moodle 3.11 compatible plugin, see the [migration guide](./format/migration) for more information.
+
+## Extending the format base class
+
+All format plugins require a lib.php file containing a format_pluginname class. This class should extend `core_courseformat\base` and define how the plugin will integrate with the core_courseformat subsystem.
+
+Here are the main features in course formats and responsible for them format_base functions.
+
+## Course sections
+
+There is existing functionality in Moodle core to support organizing course modules into sections. Course format plugins do not have to use them but most of them do. Database table `course_sections` stores basic information about sections. Also section info is cached and returned by `format->get_modinfo()` (or the global function `get_fast_modinfo()`) so every action changing the sections must be followed by rebuild_course_cache(). Course module must always belong to the section. Even if your course format does not use sections, the section with the number 0 is always created.
+
+You must define `$string['sectionname']` if your language file even if the format does not use sections because it can be called unconditionally from other parts of the code, even though it won't be displayed.
+
+| `core_courseformat\base` Overridable method | Description |
+|---|---|
+| `uses_sections()` | returns true or false if the format uses sections or not. There is a global function View pluginskel recipe
+
+
+import PluginskelRecipe from '!!raw-loader!./_examples/pluginskel_recipe.yaml';
+
+{PluginskelRecipe}
+
+
+`course_format_uses_sections()` that invokes it. It affects default navigation tree building. Various modules and reports may call this function to know whether to display the section name for the particular module or not. | +| `get_default_section_name()` | This method gets the default section name if the user has not provided a value for the section name. In format_base, it basically calls `get_section_name()`, which returns the `$string['sectionname']` + the section number of the current section, if available, or blank, otherwise. It can be used in conjunction with your course format's `get_section_name()` implementation. For reference, please refer to the implementations in format_topics and format_weeks classes. | +| `get_section_name()` | Returns the name for a particular section. This function may be called often so it should use only fields cached in section_info object (field course_sections.name is always cached)
In 3.0+, it checks if the `$string['sectionname']` is available in the lang file. If the section name string is not available, it returns an empty string. | +| `get_view_url()` | Returns the URL for a particular section, it can be either anchored on course view page or separate page. See parent function PHPdocs for more details | +| `is_section_current()` | Specifies if the section is current, for example, current week or highlighted topic. This function is only used if your renderer uses it for example if your renderer extends format_section_renderer_base. This function is not called from anywhere else in Moodle core. | +| `get_section_highlighted_name()` | Return the textual label for a current/highlighted section.| +| `set_section_number()` | Setup the format base instance to display a single section instead of all. This method is used to prepare the format base instance to render the course. | +| `get_section_number()` | Return zero if the course will deploy all sections or a section number if the current page is only presenting a single section. | +| `get_course_display()` | Return `COURSE_DISPLAY_SINGLEPAGE` or `COURSE_DISPLAY_MULTIPAGE` depending if the course has multiple section per page or not. | +| `get_last_section_number()` | Returns the last section | +| `page_title()` | Formats can override this method to alter the page title. | + +### Course features + +The format base class has several methods to integrate the course format with the frontend course editor and its webservices. + +| `core_courseformat\base` Overridable method | Description | +|---|---| +| `ajax_section_move()` | Code executed after sections were rearranged using drag and drop. See the example in format_topics where sections have automatic names depending on their sequence number | +| `uses_course_index()` | Return true if the course format is compatible with the course index drawer. Note that classic based themes are not compatible with the course index. | +| `uses_indentation()` | If the format uses the legacy activity indentation. | +| `supports_components()` | Since Moodle 4.0 the course is rendered using reactive UI components. This kind of component will be the only standard in Moodle 4.3+ but, until then, formats can override this method to specify if they want to use the previous UI elements or the new ones. | +| `supports_news()` | Determine if the news forum is mandatory or not on the course format. | +| `get_default_blocks()` | Course format can specify which blocks should be added to the course page when the course is created in this format.
If the course format is changed during course edit, blocks are not changed.
Whatever course format specifies in the method, site admin can override it with `$CFG->defaultblocks_override` or `$CFG->defaultblocks_pluginname` | +| `extend_course_navigation()` | This function is called when a navigation tree is built.
Node for the course will be created in navigationlib for you and all standard available branches like 'Participants' or 'Reports' will be added to it. After that course format can add nodes for sections and modules. There is a default implementation that adds branches for course sections and modules under them. Or if the course format does not use sections, all modules will just be placed under course mode. The course format is able to override the default navigation tree building.
Note that if navigationlib can not find the node for the current course module, the node will be added automatically (after this callback). | + +### Course format options + +The core table `course_format_options` in Moodle database is designed to store additional options for course formats. Those options may belong for the whole course or just for course section. + +Course format options must not have the same names as fields in database table `course`, section options must not have the same names as fields in `course_sections`. Also, make sure names do not duplicate completion and conditional fields in edit forms. + +When the teacher changes the course format in the course edit form AND the old and the new course formats share the same option name, the value of this option is copied from one format to another. For example, if the course had format Topics and had 8 sections in it and teacher changes format to Weeks, the course will have 8 weeks in it. + +During backup the course format options are stored as if they were additional fields in `course` table. Do not store IDs of elements (courses, sections, etc.) in course format options because they will not be backed up and restored properly. You can use section numbers because they are relative inside the course. If absolute ids are necessary you can create your own backup/restore scripts, see Backup API. + +Webservices expect course format options to be passed in additional entities but for backward compatibility `numsections`, `hiddensections` and `coursedisplay` can also be passed as if they were fields in `course` table. + +| `core_courseformat\base` Overridable method | Description | +|---|---| +| `course_format_options()` | By overriding this method course format specifies which additional options it has for course | +| `section_format_options()` | By overriding this method course format specifies which additional options it has for course section. Note that since section information is cached you may want to cache some additional options as well. See PHPdocs for more information | +| `get_format_options()` | (usually no need to override) low level function to retrieve course format options values. It is more convenient to use methods get_course() and get_section() | +| `create_edit_form_elements()` | This function is called to alter course edit form and standard section edit form. The default implementation creates simple form elements for each option defined in either `course_format_options()` or `section_format_options()`. Overwrite it if you want to have more comprehensive form elements or if you do not want options to appear in edit forms, etc. | +| `edit_form_validation()` | Overwrite if course format plugin needs additional validation for it's option in course edit form | +| `update_format_options()` | (usually no need to override) low level function to insert/update records in db table `course_format_options` | +| `update_course_format_options()` | updates course format options with the data from the edit course form. The plugin can override for example to include calculated options fields, especially when the course format is being changed. For example, format_topics and format_weeks automatically fill field `numsections` when the user switches from other format | +| `update_section_format_options()` | updates course format options for the section with the data from the edit section form | +| `editsection_form()` | Return an instance of moodleform to edit a specified section. Default implementation returns instance of `editsection_form` that automatically adds additional fields defined in section_format_options() | +| `get_default_course_enddate()` | Overwrite if the course format is time-based. The base class calculates the default course end date based on the number of sections. | +| `delete_format_data()` | This hook method is called when the course is deleted and can be used to remove any course data not stored in the standards `course_format_options` and `course` tables (like user preferences, for example). | + +Course format base helpers +The format base class is used for all the core_courseformat integrations, from settings to rendering. All course output classes will receive the course format instance as a primary param and the class has several helper methods to get information about the format. + +| `core_courseformat\base` Overridable method | Description | +|---|---| +| `get_course()` | (no need to override) returns object with all fields from db table `course` AND all course format options | +| `get_section()` | (no need to override) returns instance of section_info. It will contain all fields from table `course_sections` and all course format options for this section | +| `get_sections()` | Return all course sections (it is just a wrapper fo the modinfo get_section_info_all) | +| `get_course_display()` | Returns if the course is using a multi page or a single page display (`COURSE_DISPLAY_MULTIPAGE` or `COURSE_DISPLAY_SINGLEPAGE`) | +| `get_modinfo()` | Returns the current course modinfo (equivalent to get_fast_modinfo but without specifying the course) | +| `get_renderer()` | Return the course format renderer instance | +| `get_output_classname()` | This method gets a relative output class path (for example, "content\\section") and returns the correct output class namespace depending on if the format has overridden outputs or not. See [overriding output classes](#override-output-classes) section for more information. | +| `is_section_current()` | Returns if a specific section is marked as current (highlighted) or not. | +| `show_editor()` | Do all the user and page validations to know if the current course display has to include editor options or not. This includes both page editing mode and user capabilities. You can pass an array of capabilities which should be checked. If none specified, will default to `moodle/course:manageactivities`. | + +## Rendering a course + +Each format plugin is responsible for rendering the course in the format.php file, this means each plugin can choose how to render the course content. However, there are some conventions on how a course should be rendered to integrate the plugin with the existing components. + +The course rendering is done using four mains elements: + +- **File view.php:** responsible for setting up the format base instance and rendering the content. +- **Course format renderer:** all format plugins must provide its own version of the `core_courseformat\output\section_renderer` (or provide an equivalent class with all the necessary methods). +- **Output classes:** by default all course elements have a specific output class inside course/format/output/local folder. Each one of them is responsible for generating the necessary data to render the templates. Format plugins can provide alternative versions of those output classes (see [override output classes](#override-output-classes) for more information) +- **Mustache templates:** each output class has its equivalent mustache template inside course/format/templates. All the course content is rendered using a single "content" template that includes all the rest as sub-templates. For this reason, a plugin that wants to override some templates must provide some extra templates in order to keep the template structure. See [Creating the basic output structure](#creating-the-basic-output-structure) section for more information. + +Unless there's a reason for it, the course structure should be rendered overriding the standard outputs and mustache templates. + +## Format output classes and templates + +The following diagram shows the standard output classes structure: + + + +There are three renderer methods used for refreshing fragments of the course page: + +- **render_content:** used to render the full course. This method is not necessary as the content output itself will be used by default. +- **course_section_updated:** needed when the frontend needs to render a particular section. It is used mostly when a new section is created. By default it renders the core_courseformat\output\local\content\section output. +- **Course_section_updated_cm_item:** used every time the frontend needs to update an activity card on the course page. By default it will render the core_courseformat\output\local\content\section\cmitem. The reason why it uses this specific output is that it renders the full course module list item, not just the activity card. + +By default, the base renderer methods will use the format output components to render the full course. In case your plugins have special needs, it is possible to override those three methods directly into the format renderer class. + +### Override output classes + +Instead of having several renderer methods on a single file, the core_courseformat subsystem splits the output logic through several small classes, each one for a specific UI component. Format plugins can easily override specific classes to alter the template data. + +The course format base class has a special method called **get_output_classname** that returns the overridden class name if available in the format plugin (or the core one if not). In order to detect the format classes, your plugin must place the overridden one in the equivalent path inside your plugin format_pluginname\output\courseformat\ folder + +For example, if a format plugin wants to add new options to the section action menu it should override the core_courseformat\output\local\content\section\controlmenu. To do so the plugin class should be format_pluginname\output\courseformat\content\section\controlmenu. You can find an example of an overridden output in the "course/format/topics/classes/output/courseformat/content/section/controlmenu.php" file. + +### Creating the basic output structure + +By default, the course renderer will use the core_courseformat output classes and templates. To override some parts of the course elements the plugin must provide a minimum output classes and template structure. + +#### Basic output classes + +It is recommended your plugin overrides the 3 main course format elements: + +- format_pluginname\output\courseformat\content +- format_pluginname\output\courseformat\content\section +- format_pluginname\output\courseformat\content\section\cmitem + +Those output classes should extend the equivalent core ones but, at least, they should override the **get_template_name** method to redirect the rendering template to the overridden template. It could also override the export_for_template to alter the template data if necessary. +This is the minimum output classes your plugin must provide: + +
{getExample(OutputContentProps, OutputContent)}
+
+ {getExample(OutputSectionProps, OutputSection)}
+
+ {getExample(OutputCmitemProps, OutputCmitem)}
+
+
+
+
+Due to the fact that mustache blocks are not scoped, blocks can be overridden by any of the parent templates. This generates some possible scenarios depending on your format needs:
+
+- **[Scenario 1](#scenario-1-adding-blocks-directly-on-the-three-main-mustache-templates):** your format just overrides a few course elements like adding menu options o tweaking the sections or activity HTML.
+- **[Scenario 2](#scenario-2-keep-all-the-intermediate-templates-structure):** your plugin needs a big UI change, keeping the general structure but altering several course elements.
+- **[Scenario 3](#scenario-3-just-keep-a-few-renderer-methods):** Your plugin is a completely different thing that does not follow any standard course rule. Almost everything in your format is done from scratch.
+
+#### Scenario 1: adding blocks directly on the three main mustache templates
+
+If your format only overrides a few inner templates of the course, the overriding blocks can be located in one of the 3 basic templates:
+
+- **local/content:** for general course structure elements
+- **local/content/section:** to alter section elements
+- **local/content/section/cmitem:** to alter activity elements
+
+View example: override course format templates using mustache blocks
+
+
+For example, imagine a mustache file "original/path/parent" including "original/path/to/the/template":
+
+```handlebars
+{{$ original/path/to/the/template }}
+ {{> original/path/to/the/template }}
+{{/ original/path/to/the/template }}
+```
+
+Using this pattern any parent template can replace the sub-template doing:
+
+```handlebars
+{{! Then include the parent template }}
+{{< original/path/parent }}
+ {{! Add custom blocks. }}
+ {{$ original/path/to/the/template }}
+ {{> new/template/path }}
+ {{/ original/path/to/the/template }}
+{{/ original/path/parent }}
+```
+
+Or can wrap the content with extra HTML:
+
+```handlebars
+{{! Then include the parent template }}
+{{< original/path/parent }}
+ {{! Add custom blocks. }}
+ {{$ original/path/to/the/template }}
+
+
+ {{> new/template/path }}
+
+ {{/ original/path/to/the/template }}
+{{/ original/path/parent }}
+```
+
+Of even replace the fill block by an alternative HTML:
+
+```handlebars
+{{! Then include the parent template }}
+{{< original/path/parent }}
+ {{! Add custom blocks. }}
+ {{$ original/path/to/the/template }}
+
+ Here you can use the template {{outputdata}}
+
+ {{/ original/path/to/the/template }}
+{{/ original/path/parent }}
+```
+
+
+
+
+Benefits of this approach:
+
+- Easy to maintain in a short term. All templates overrides are located on one of the 3 main templates.
+- Fewer files. The plugin only contains the three mains files and the overridden ones.
+
+Negatives of this approach:
+
+- Harder to maintain in the long run. Is it possible that the format must refactor the template structure if future versions require more main templates to be refreshed via ajax.
+
+#### Scenario 2: keep all the intermediate templates structure
+
+If your plugin needs a big UI change, altering a considerable number of the course elements at different levels (course, section and/or activity), the previous approach is not recommended as it may require more code refactoring in future versions.
+
+To keep your plugin more stable through time the best approach is to override the mustache blocks at the inner parts of the mustache files structure instead of at the main elements. It will require more code but the final result will be more stable.
+
+View example
+
+
+If a format requires to override the activity visibility badges your format_pluginname/local/content/section/cmitem template will look like:
+
+```handlebars
+{{! include the original course format template block }}
+{{< core_courseformat/local/content/section/cmitem }}
+ {{! Add custom blocks here. }}
+ {{$ core_courseformat/local/content/section/badges }}
+ {{> format_pluginname/local/content/cm/badges }}
+ {{/ core_courseformat/local/content/section/badges }}
+{{/ core_courseformat/local/content/section/cmitem }}
+```
+
+
+
+
View example
+
+
+Let's say your format requires overriding the activity visibility badges as in the previous scenario example. Apart from the three main templates, the plugin must create several new template overrides until it reacher the activity badges one:
+
+CM item main file: format_pluginname/local/content/section/cmitem template:
+
+```handlebars
+{{! include the original course format template block }}
+{{< core_courseformat/local/content/section/cmitem }}
+ {{$ core_courseformat/local/content/cm }}
+ {{> format_pluginname/local/content/cm }}
+ {{/ core_courseformat/local/content/cm }}
+{{/ core_courseformat/local/content/section/cmitem }}
+```
+
+The content/cm template:
+
+```handlebars
+{{< core_courseformat/local/content/cm/activity }}
+ {{$ core_courseformat/local/content/cm/badges }}
+ {{> format_pluginname/local/content/cm/badges }}
+ {{/ core_courseformat/local/content/cm/badges }}
+{{/ core_courseformat/local/content/cm/activity }}
+```
+
+The content/cm/badges will contain only the overridden HTML.
+
+Apart from the templates files, the plugin could also provide overridden output classes to ensure that future versions will remain compatible if new ajax partials are required:
+
+In the example the extra output classes can look like:
+
+```php tile="format_pluginname\output\local\content\cm class"
+
+
+
+Benefits of this approach:
+
+- Easy to maintain in the long term. The code will remain the same if future versions require more main templates.
+- Overridden templates can be rendered as a regular course format output. Because each of the overridden mustaches has also its output class, the course format subsystem can render them independently.
+
+Negatives of this approach:
+
+- Requires extra files to keep the structure. Most of the files are just there to ensure the course format subsystem knows how to render them if needed in the future.
+
+#### Scenario 3: just keep a few renderer methods
+
+If your plugin is a completely different thing from a regular course you are most likely on your own. Your format may use a completely different set of renderer methods or output classes and you already have your own template structure.
+
+In that case, you may keep it that way. However, there are a few things you could add to your plugin in order to make it compatible with the new course output. Take in mind that the new course editor expects some conventions about renderer methods that should be easy to incorporate into your plugin.
+
+The first thing you should add is all the section and activities data attributes (see [course elements data attributes](#course-elements-data-attributes). The new course editor did not use CSS classes anymore but data attributes. If your format should be able to interact with the standard editor those attributes are necessary.
+
+Secondly, the new frontend JS modules use renderer methods to refresh a full section or an activity. If your format wants to keep this feature you should implement two methods on your renderer class:
+
+- **course_section_updated:** to render a single section.
+- **course_section_updated_cm_item:** to render a single course module item. Note that this method does not render an activity card only but also the full course item. In a regular course, this also includes the "li" element.
+
+And third, consider using "local/content" as your main course template, "output\local\content" as your main output class or, if you don't use output classes, use the render_content renderer method to print a full course. Those are the expected names to render the full course. For now, they are only used in your plugin "format.php" file but nobody can guarantee this will continue this way in the future.
+
+## The course editor structure
+
+The core_courseformat provides several JavaScript modules that will be enabled when a teacher edits the course. Those libraries use a reactive pattern to keep the course updated when some edit action is executed.
+
+The following diagram represents the data flow of the new architecture:
+
+
+
+### Enabling the course editor
+
+To enable the course editor in your format you should add the following method to your format base class (in your course/format/pluginname/lib.php):
+
+```php
+/**
+ * Enable the component based content.
+ */
+public function supports_components() {
+ return true;
+}
+```
+
+### Course elements data attributes.
+
+The course editor modules use data attributes to find the course elements in the page. If your plugin alters the default templates you should keep those attributes in your HTML structure.
+
+The following table describes the data attributes:
+
+| Concept | Required data attributes |
+|---------|------------------------|
+| **Section** | `data-for="section"`
`data-id={SECTION.ID}`
`data-number={SECTION.NUM}` | +| **Section header** | `data-for="section_title"`
`data-id={SECTION.ID}
data-number={SECTION.NUM}` | +| **Course module item (activity)** | `data-for="cmitem"`
`data-id={CM.ID}` | +| **Course sections list** | `data-for="course_sectionlist"` | +| **Section course modules list** | `data-for="cmlist"` | +| **Course module action link** | `data-action={ACTIONNAME}`
`data-id={CM.ID}` | +| **Section action link** | `data-action={ACTIONNAME}`
`data-id={SECTION.ID}` | +| **Section info** | `data-for="sectioninfo"` | + +## Implementing format specific actions + +All course editing actions done by the user will trigger what is called "state actions" that will update the backend, but also send back information on how to update the frontend in real time. The core state actions are defined in the `core_courseformat\stateactions` class. However, each format plugin extend this class to add its own actions by placing them in the `course/format/PLUGINNAME/classes/courseformat/stateactions.php` file. + +All state action will receive the same parameters: + +- `stateupdates $updates` an object to register the state updates. This object will be used to inform the frontend about the changes. +- `stdClass $course` the course object +- `int[]` $ids the list of affected ids. They could be cmids or section ids depending on the action. +- `int $targetsectionid` optional target section id. For example, when moving a course module to a new section. +- `int $targetcmid` optional target cm id. For example, when moving a course module to a new position. + +The best example on how to implement a state action is to look at the `format_topics\courseformat\stateactions` class (located at `course/format/topics/classes/courseformat/stateactions.php`). The topics format incorporate two new state actions: `section_highlight` and `section_unhighlight`. + +Once your plugin has the integration class implemented with all the extra actions, the action will be available to be executed by the user. + +### Execute format specific action from the course page via Ajax + +Once the format provides a state action, the plugin must inform the frontend about the new action. + +As explained in previous sections, the course editor uses a reactive pattern to keep the course updated. The course editor will always modify the UI to represent the current state data. When a user executes an action, the course editor will send the action to the backend, wait for the state updates, and apply then to the frontend state data. This is what is known as `mutation`. + +The `mutations` is the only way to execute state actions from the frontend, and each plugins that implements new state actions in the backend must provide a mutation to the frontend. + +Once again, the best example on how to implement a mutation is to look at the `course/format/topics/amd/src/mutations.js`. The topics format incorporate two new mutations: `sectionHighlight` and `sectionUnhighlight`. + +The JavaScript reactive components can execute the mutation using the `this.reactive.dispatch` method. + +### Execute state actions via non-AJAX requests + +
`data-id={SECTION.ID}`
`data-number={SECTION.NUM}` | +| Section header | `#sectionid-{SECTION.ID}-title` | `data-for="section_title"`
`data-id={SECTION.ID}`
`data-number={SECTION.NUM}` | +| Course module item (activity) | `li.activity#module-{CM.ID}` | `data-for="cmitem"`
`data-id={CM.ID}` | +| Course sections list | `.course-content>ul` | `data-for="course_sectionlist"`
`Section course modules list Li.section .content .section`
`data-for="cmlist"`| +| Course module action link | `a.cm-edit-action` | `data-action={ACTIONNAME}`
`data-id={CM.ID}` | +| Section action link | `.section_action_menu` | `data-action={ACTIONNAME}`
`data-id={SECTION.ID}` | +| Section info | `.section_availability` | `data-for="sectioninfo"` | + +### Step 2: enable supports components feature + +Once your plugin has all the necessary data attributes you can disable the old YUI editor and enable the new reactive one by adding this method to your plugin base class: + +
+Tools for course administration, such as attendance tracking or appointment scheduling. +- **Assessment** (`MOD_PURPOSE_ASSESSMENT`)
+Activities that allow the evaluation and measurement of student understanding and performance.
+ - Core activities in this category: Assignment, Quiz, Workshop. +- **Collaboration** (`MOD_PURPOSE_COLLABORATION`)
+Tools for collaborative learning that encourage knowledge sharing, discussions, and teamwork.
+ - Core activities in this category: Database, Forum, Glossary, Wiki. +- **Communication** (`MOD_PURPOSE_COMMUNICATION`)
+Activities that facilitate real-time communication, asynchronous interaction, and feedback collection.
+ - Core activities in this category: BigBlueButton, Chat, Choice, Feedback, Survey. +- **Interactive content** (`MOD_PURPOSE_INTERACTIVECONTENT`)
+Engaging interactive activities that encourage active learner participation.
+ - Core activities in this category: H5P, IMS package, Lesson, SCORM package. +- **Resources** (`MOD_PURPOSE_CONTENT`)
+Activities and tools to organise and display course materials like documents, web links, and multimedia.
+ - Core activities in this category: Book, File, Folder, Page, URL, Text and media area. +- **Other** (`MOD_PURPOSE_OTHER`)
+Other types of activities. + +::: diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.mdx b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.mdx new file mode 100644 index 0000000000..95055149e0 --- /dev/null +++ b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.mdx @@ -0,0 +1,16 @@ + +This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called `mod_[modname]_mod_form`. + +:::warning + +The `mod_[modname]_mod_form` is a current exception to the class autoloading rules. + +This will be addressed in [MDL-74472](https://moodle.atlassian.net/browse/MDL-74472). + +::: + +:::info + +The following example gives a sample implementation of the creation form. It does **not** contain the full file. + +::: diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.tsx b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.tsx new file mode 100644 index 0000000000..71c4745642 --- /dev/null +++ b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.tsx @@ -0,0 +1,106 @@ +/** + * Copyright (c) Moodle Pty Ltd. + * + * Moodle is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * Moodle is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with Moodle. If not, see_plugin` class in `backup/moodle2/restore_qtype__plugin.class.php`. If the
+`define_question_plugin_structure()` method only calls `$this->add_question_*()` functions, these fields will be handled
+automatically so there is nothing more needed here. If it is adding additional paths to the `$paths[]` array, you will need to
+account for these.
+
+Add an override of the `convert_backup_to_questiondata` method, which starts by calling
+
+```php
+$questiondata = parent::convert_backup_to_questiondata($backupdata);
+```
+
+Now, find the plugin-specific paths in `$backupdata`, and add them to the `$questiondata` object at the appropriate points.
+The result should match that returned by the `qtype_::get_question_options()` method in your plugin's `questiontype.php` file.
+
+Now review your plugin's `db/install.xml` file. If your plugin defines any additional tables, you will need to define the primary
+and foreign key fields (any field that contains an ID) to be excluded from the data before hashing.
+
+In your `restore_qtype__plugin` class, add an override of the `define_excluded_identity_hash_fields()` method, which returns
+an array of fields to remove from the `$questiondata` structure. For example, if you have a table of `qtype_name_extradata`
+records with the fields `id`, `questionid` and `data`, you might need to define the following:
+
+```php title="question/type/example/backup/moodle2/restore_qtype_example_plugin.class.php"
+protected function define_excluded_identity_hash_fields(): array {
+ return [
+ '/options/extradata/id',
+ '/options/extradata/questionid',
+ ];
+}
+```
+
+The exact paths required depend on where these extra records are added in the plugin's `get_question_options()` and
+`convert_backup_to_questiondata($backupdata)` methods.
+
+Finally, check through your `get_question_options()` method to see if there is any other data attached to the `$questiondata`
+structure that is not included in the backup, it will need to be removed before hashing takes place.
+
+In your `restore_qtype__plugin` class, add an override of the `remove_excluded_question_data()` method, which removes this
+additional data, then passes `$questiondata` on to the parent method. For example, if `get_question_options()` adds a config
+setting at `$questiondata->options->pluginconfig`, you might need to define the following:
+
+```php title="question/type/example/backup/moodle2/restore_qtype_example_plugin.class.php"
+public static function remove_excluded_question_data(stdClass $questiondata, array $excludefields = []): stdClass {
+ if (isset($questiondata->options->pluginconfig)) {
+ unset($questiondata->options->pluginconfig);
+ }
+ return parent::remove_excluded_question_data($questiondata, $excludefields);
+}
+```
+
+### I did all that and the tests still fail!
+
+If something is still failing and you can't tell why, the best option is to run the unit test with XDebug, and put a breakpoint on
+the `return` line of `restore_questions_parser_processor::generate_question_identity_hash()`. Most tests will hit this 3 times for
+each question: Once when reading the backup the first time and creating a restored question, again when reading it the second time,
+and finally when hashing the restored question for comparison. Comparing the contents of `$questiondata` between those last two
+samples should help you find why they are matching incorrectly, or not matching correctly, depending on the test.
+
+## Where can I see some examples?
+
+- `qtype_calculated` has an example of overriding `restore_qtype_plugin::convert_backup_to_questiondata()`, to add additional
+ fields from the backup to the `$questiondata` structure, to add plugin-specific options and answer fields.
+- `qtype_truefalse` has an example of overriding `restore_qtype_plugin::define_excluded_identity_hash_fields()` to remove the
+ ID fields used to reference the `trueanswer` and `falseanswer` answer records.
+- `qtype_multianswer` has an example of overriding `restore_qtype_plugin::remove_excluded_question_data()` to remove the array
+ of `subquestions`, which are defined and restored separately in the backup so will not be part of the backup data for the question.
diff --git a/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule.md b/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule.md
new file mode 100644
index 0000000000..f8be96b094
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule.md
@@ -0,0 +1,4 @@
+
+The rule class defines the behaviour of your rule and how it will restrict access for users attempting a quiz.
+
+Please refer to the inline phpdocs of the [mod_quiz::access_rule_base class](https://github.com/moodle/moodle/blob/main/mod/quiz/classes/local/access_rule_base.php) for detailed descriptions of the functions and meaning.
diff --git a/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule.php b/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule.php
new file mode 100644
index 0000000000..3732aac8fa
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule.php
@@ -0,0 +1,120 @@
+use mod_quiz\form\edit_override_form;
+use mod_quiz\form\preflight_check_form;
+use mod_quiz\quiz_settings;
+use mod_quiz\local\access_rule_base;
+use mod_quiz_mod_form;
+use MoodleQuickForm;
+
+class quizaccess_pluginname extends access_rule_base {
+
+ /**
+ * Below are methods inherited from mod_quiz\local\access_rule_base. All of these functions,
+ * are optional to rewrite - although it depends on the behaviour of your rule which will
+ * determine which functions should be reimplemented.
+ */
+
+ public function __construct($quizobj, $timenow) {
+ $this->quizobj = $quizobj;
+ $this->quiz = $quizobj->get_quiz();
+ $this->timenow = $timenow;
+ }
+
+ public static function make(quiz_settings $quizobj, $timenow, $canignoretimelimits) {
+ return null;
+ }
+
+ public function prevent_new_attempt($numprevattempts, $lastattempt) {
+ return false;
+ }
+
+ public function prevent_access() {
+ return false;
+ }
+
+ public function is_preflight_check_required($attemptid) {
+ return false;
+ }
+
+ public function add_preflight_check_form_fields(preflight_check_form $quizform,
+ MoodleQuickForm $mform, $attemptid) {
+ // Do nothing by default.
+ }
+
+ public function validate_preflight_check($data, $files, $errors, $attemptid) {
+ return $errors;
+ }
+
+ public function notify_preflight_check_passed($attemptid) {
+ // Do nothing by default.
+ }
+
+ public function current_attempt_finished() {
+ // Do nothing by default.
+ }
+
+ public function description() {
+ return '';
+ }
+
+ public function is_finished($numprevattempts, $lastattempt) {
+ return false;
+ }
+
+ public function end_time($attempt) {
+ return false;
+ }
+
+ public function time_left_display($attempt, $timenow) {
+ $endtime = $this->end_time($attempt);
+ if ($endtime === false) {
+ return false;
+ }
+ return $endtime - $timenow;
+ }
+
+ public function attempt_must_be_in_popup() {
+ return false;
+ }
+
+ public function get_popup_options() {
+ return [];
+ }
+
+ public function setup_attempt_page($page) {
+ // Do nothing by default.
+ }
+
+ public function get_superceded_rules() {
+ return [];
+ }
+
+ public static function add_settings_form_fields(
+ mod_quiz_mod_form $quizform, MoodleQuickForm $mform) {
+ // By default do nothing.
+ }
+
+ public static function validate_settings_form_fields(array $errors,
+ array $data, $files, mod_quiz_mod_form $quizform) {
+ return $errors;
+ }
+
+ public static function get_browser_security_choices() {
+ return [];
+ }
+
+ public static function save_settings($quiz) {
+ // By default do nothing.
+ }
+
+ public static function delete_settings($quiz) {
+ // By default do nothing.
+ }
+
+ public static function get_settings_sql($quizid) {
+ return ['', '', []];
+ }
+
+ public static function get_extra_settings($quizid) {
+ return [];
+ }
+}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule_overridable.md b/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule_overridable.md
new file mode 100644
index 0000000000..51d8c2b7f7
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule_overridable.md
@@ -0,0 +1,4 @@
+
+Most quiz settings can be overridden on a per user and/or group level and you can extend this ability to your rule as well. To make your rule overridable, you must implement the `rule_overridable` interface in your rule class definition.
+
+Please refer to the inline phpdocs of the [mod_quiz::rule_overridable interface](https://github.com/moodle/moodle/blob/main/mod/quiz/classes/local/rule_overridable.php) for detailed descriptions of the functions and meaning.
diff --git a/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule_overridable.php b/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule_overridable.php
new file mode 100644
index 0000000000..58c57ed5df
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/quizaccess/_examples/rule_overridable.php
@@ -0,0 +1,100 @@
+use mod_quiz\form\edit_override_form;
+use mod_quiz\local\access_rule_base;
+use mod_quiz\local\rule_overridable;
+use MoodleQuickForm;
+
+class quizaccess_pluginname extends access_rule_base implements rule_overridable {
+
+ /**
+ * All of the below rule_overridable interface functions will need to be implemented.
+ */
+
+ public static function add_override_form_fields(edit_override_form $quizform, MoodleQuickForm $mform): void {
+ // Use the $mform to add the rule override fields...
+ $mform->addElement(
+ 'select',
+ 'plgn_setting1',
+ get_string('plgn_setting1', 'quizaccess_pluginname'),
+ ['A', 'B', 'C'],
+ );
+
+ $mform->addElement(
+ 'select',
+ 'plgn_setting2',
+ get_string('plgn_setting2', 'quizaccess_pluginname'),
+ ['1', '2', '3'],
+ );
+ }
+
+ public static function get_override_form_section_header(): array {
+ // Return the label and content of the section header in an array.
+ return ['name' => 'pluginname', 'title' => get_string('pluginname', 'quizaccess_pluginname')];
+ }
+
+ public static function get_override_form_section_expand(edit_override_form $quizform): bool {
+ // Determine if rule section in override form should load expanded.
+ // Should typically return true if the quiz has existing rule settings.
+ global $DB;
+ return $DB->record_exists('quizaccess_pluginname', ['quiz' => $quizform->get_quiz()->id]);
+ }
+
+ public static function validate_override_form_fields(array $errors,
+ array $data, array $files, edit_override_form $quizform): array {
+ // Check and push to $errors array...
+ return $errors;
+ }
+
+ public static function save_override_settings(array $override): void {
+ // Save $override data to plugin settings table...
+ global $DB;
+
+ $plgnoverride = (object)[
+ 'overrideid' => $override['overrideid'],
+ 'setting1' => $override['plgnm_setting1'],
+ 'setting2' => $override['plgnm_setting2'],
+ ];
+
+ if ($plgnoverrideid = $DB->get_field('quizaccess_pluginname_overrides', 'id', ['overrideid' => $override['overrideid']])) {
+ $plgnoverride->id = $plgnoverrideid;
+ $DB->update_record('quizaccess_pluginname_overrides', $plgnoverride);
+ } else {
+ $DB->insert_record('quizaccess_pluginname_overrides', $plgnoverride);
+ }
+ }
+
+ public static function delete_override_settings($quizid, $overrides): void {
+ // Remove $overrides from $quiz.
+ global $DB;
+ $ids = array_column($overrides, 'id');
+ list($insql, $inparams) = $DB->get_in_or_equal($ids);
+ $DB->delete_records_select('quizaccess_pluginname_overrides', "id $insql", $inparams);
+ }
+
+ public static function get_override_setting_keys(): array {
+ // Return string array of all override form setting keys.
+ return ['plgnm_setting1', 'plgnm_setting2'];
+ }
+
+ public static function get_override_required_setting_keys(): array {
+ // Return string array of override form setting keys that are required.
+ return ['plgnm_setting1'];
+ }
+
+ public static function get_override_settings_sql($overridetablename): array {
+ // Return an array of selects, joins and parameters to be used to query relevant rule overrides...
+ return [
+ "plgnm.setting1 plgnm_setting1, plgnm.setting2 plgnm_setting2",
+ "LEFT JOIN {quizaccess_pluginname_overrides} plgnm ON plgnm.overrideid = {$overridetablename}.id",
+ [],
+ ];
+ }
+
+ public static function add_override_table_fields($override, $fields, $values, $context): array {
+ // Extend the override table view by adding fields and values that display the rule's overrides.
+ if (!empty($override->plgnm_setting1)) {
+ $fields[] = get_string('pluginname', 'quizaccess_pluginname');
+ $values[] = "{$override->plgnm_setting1}, {$override->plgnm_setting2}";
+ }
+ return [$fields, $values];
+ }
+}
diff --git a/versioned_docs/version-5.1/apis/plugintypes/quizaccess/index.md b/versioned_docs/version-5.1/apis/plugintypes/quizaccess/index.md
new file mode 100644
index 0000000000..8c9b33f1b1
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/quizaccess/index.md
@@ -0,0 +1,86 @@
+---
+title: Quiz access rule sub-plugins
+tags:
+ - Quiz
+ - Access
+ - Rule
+ - Subplugin
+ - Plugintype
+ - Override
+---
+
+import { ComponentFileSummary } from '../../../_utils';
+
+Quiz access rule sub-plugins extend the ability to add conditions a user must meet to attempt a given quiz.
+
+The following rules are readily available as part of Moodle core:
+
+- `quizaccess_delaybetweenattempts`
+- `quizaccess_ipaddress`
+- `quizaccess_numattempts`
+- `quizaccess_offlineattempts`
+- `quizaccess_openclosedate`
+- `quizaccess_password`
+- `quizaccess_seb`
+- `quizaccess_securewindow`
+- `quizaccess_timelimit`
+
+## File structure
+
+Quiz access rule sub-plugins are located in the `/mod/quiz/accessrule` directory. A plugin should not include any custom files outside of it's own plugin folder.
+
+Each plugin is in a separate subdirectory and consists of a number of mandatory files and any other files the developer is going to use.
+
+
+
+This file contains the main repository class definition, which must extend the core `\repository` class. By extending the base class and overriding some of the class methods, the plugin can configure standard features and behaviours. See [Administration API](../../subsystems/admin/index.md) for more information.
+
+
+
+### db/access.php
+
+import RepositoryAccessExample from '!!raw-loader!./_examples/access.php';
+
+
+
+
+> The return types that your plugin supports will be presented as options to the user when they are adding a file from the file picker. The `FILE_EXTERNAL` option is not reflected in this list as this is an internal feature of your API.
+>
+> 
+
+
+
+
+```php
+function supported_returntypes() {
+ return FILE_INTERNAL | FILE_EXTERNAL | FILE_REFERENCE | FILE_CONTROLLED_LINK;
+}
+```
+
+
+
+
+The return values influence the choices offered to a user when selecting a file in file picker. Consider the screenshot above, which is from the dialogue that appears directly after choosing (but before uploading) a file in mod_resource. The three options result from `FILE_INTERNAL`, `FILE_REFERENCE`, and `FILE_CONTROLLED_LINK` being present. `FILE_REFERENCE` corresponds to the "alias/shortcut" option.
+
+The option `FILE_EXTERNAL` is never reflected in the file picker for mod_resource, so its absence or presence in supported_returntypes() is never reflected here. However, `FILE_EXTERNAL` is the only return type supported by mod_url: For mod_url, file picker will only(!) list repositories that support `FILE_EXTERNAL`.
+
+This implies that a plugin that uses a file picker is able to narrow the set of supported return types. For example, assignsubmission_file disallows `FILE_EXTERNAL` and `FILE_REFERENCE`.
+
+In the end, which type is
+used by Moodle depends on the choices made by the end user (for example inserting a link, will result in `FILE_EXTERNAL`-related functions being used, using a 'shortcut/alias' will result in the '`FILE_REFERENCE`'-related functions being used).
+
+### supported_filetypes()
+
+If your plugin only supports certian file types, then you should implement the optional `supported_filetypes()` method.
+
+This method is used to hide repositories when they don't support certain file types - for example, if a user is inserting a video then any repository which does not support videos will not be shown.
+
+Supported file types can be specified using standard mimetypes (such as `image/gif`) or file groups (such as `web_image`). For a full list of the supported mimetypes and groups, see the [`core_filetypes`](https://github.com/moodle/moodle/blob/v4.0.0/lib/classes/filetypes.php#L47) class.
+
+
+
+
+```php
+function supported_filetypes() {
+ // Allow any kind of file.
+ return '*';
+}
+```
+
+
+
+
+```php
+function supported_filetypes() {
+ // Example of image mimetypes.
+ return ['image/gif', 'image/jpeg', 'image/png'];
+}
+```
+
+
+
+
+```php
+function supported_filetypes() {
+ // Example of a file group.
+ return ['web_image'];
+}
+```
+
+
+
+
+### Course and User Repository Instances.
+
+A system-wide instance of a repository is created when it is enabled. It is also possible to support both course, and user specific repositories.. This can be achieved by setting the `enablecourseinstances` and `enableuserinstances` options. There are three ways that this can be done:
+
+1. Define **$string\['enablecourseinstances'\]** and **$string\['enableuserinstances'\]** in your plugin's language file. You can check an example in the [filesystem repository](https://github.com/moodle/moodle/blob/v4.0.0/repository/filesystem/lang/en/repository_filesystem.php).
+2. The plugin must provide a **get_instance_option_names** method which returns at least one instance option name. This method defined the specific instances options, if none instance attribute is needed, the system will not allow the plugin to define course and user instances. Note, you must not define the form fields for these options in the **type_config_form()** function. For example, [filesystem repository](https://github.com/moodle/moodle/blob/v4.0.0/repository/filesystem/lib.php#L439).
+3. Several 'core' repositories use the **db/install.php** to create the original repository instance by constructing an instance of the **repository_type** class. The options can be defined in the array passed as the second parameter to the constructor. For example [Wikipedia repository](https://github.com/moodle/moodle/blob/v4.0.0/repository/wikimedia/db/install.php).
+
+### Developer-defined API
+
+These are settings that are configured for the whole Moodle site and not per instance of your plugin. All of these are optional, without them there will be no configuration options in the Site administration > Plugins > Repositories > pluginname page.
+
+#### get_type_option_names(): array
+
+This function must be declared static
+
+Optional. Return an array of string. These strings are setting names. These settings are shared by all instances.
+Parent function returns an array with a single item - pluginname.
+
+
+
+
+```php
+public function get_file($url, $filename = '') {
+// Default implementation from the base 'repository' class
+ $path = $this->prepare_file($filename); // Generate a unique temporary filename
+ $curlobject = new curl();
+ $result = $curlobject->download_one($url, null, ['filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT]);
+ if ($result !== true) {
+ throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
+ }
+ return ['path'=>$path, 'url'=>$url];
+}
+```
+
+
+
+
+Slightly extended version taken from repository_equella
+
+```php
+public function get_file($reference, $filename = '') {
+ global $USER;
+ // Replace the line below by any method your plugin have to check a reference.
+ $details = example_external_server::get_details_by_reference($reference->reference));
+ if (!isset($details->url) || !($url = $this->appendtoken($details->url))) {
+ // Occurs when the user isn't known..
+ return null;
+ }
+ $path = $this->prepare_file($filename);
+ $cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
+ $curlobject = new curl(['cookie'=>$cookiepathname]);
+ $result = $curlobject->download_one(
+ $url,
+ null,
+ ['filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT]
+ );
+ // Delete cookie jar.
+ if (file_exists($cookiepathname)) {
+ unlink($cookiepathname);
+ }
+ if ($result !== true) {
+ throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
+ }
+ return ['path'=>$path, 'url'=>$url];
+}
+```
+
+
+
+
+#### get_link($url)
+
+Used with `FILE_EXTERNAL` to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.
+
+#### get_file_source_info($source)
+
+Takes the 'source' field from 'get_listing' (as returned by the user's browser) and returns the value to be stored in files.source field in DB (regardless whether file is picked as a copy or by reference). It indicates where the file came from. It is advised to include either full URL here or indication of the repository.
+Examples: 'Dropbox: /filename.jpg', 'http://fullurl.com/path/file', etc.
+
+This value will be used to display warning message if reference can not be restored from backup. Also it can (although not has to) be used in get_reference_details() to produce the human-readable reference source in the fileinfo dialogue in the file manager.
+
+### Search functions (optional)
+
+These functions allow you to implement search functionality within your repository.
+
+#### print_search
+
+When a user clicks the search button on file picker, this function will be called to return a search form. By default, it will create a form with single search bar - you can override it to create a advanced search form.
+
+A custom search form must include the following:
+
+- A text field element named **s**, this is where users will type in their search criteria
+- A hidden element named **repo_id** and the value must be the id of the repository instance
+- A hidden element named **ctx_id** and the value must be the context id of the repository instance
+- A hidden element named **sesskey** and the value must be the session key
+
+
+
+```
+
+## Use images in CSS
+
+The following is how you would use the images from within CSS/SCSS as background images.
+
+```css
+.divone {
+ background-image: url([[pix:theme|imageone]]);
+}
+
+.divtwo {
+ background-image: url([[pix:theme|subdir/imagetwo]]);
+}
+```
+
+A placeholder is used within the CSS to allow use of a pix icon. During the CSS/SCSS compilation, these placeholders are converted into a URL which the browser can fetch and serve.
+
+:::note
+
+Notice that the image file extension included. The reason for this leads us into the next topic, how to override images.
+
+:::
+
+## Override images
+
+From within a theme you can **very** easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle.
+So, for instance, if there is a need to override the following images:
+
+1. `/pix/moodlelogo.png`
+1. `/pix/i/user.svg`
+1. `/mod/chat/pix/monologo.svg`
+
+Simply add the replacement images to the theme in the following locations:
+
+1. `/theme/themename/pix_core/moodlelogo.png`
+1. `/theme/themename/pix_core/i/user.svg`
+1. `/theme/themename/pix_plugins/mod/chat/monologo.svg`
+
+:::note
+
+A `pix_core` directory has been created in the theme to store the replacement images. For a specific activity module like chat, the directory `pix_plugins/mod/chat` is needed. This directory is `pix_plugins` and then the plugin type (`mod`) and then the plugin name (`chat`).
+
+:::
+
+Another noteworthy aspect is that Moodle not only searches for replacements of the same image type (svg, png, jpg, gif, and so on) but also replacements in any image format. This is why the image file extension was never specified when working with our images above.
+This means that the following would also work:
+
+1. `/theme/themename/pix_core/moodlelogo.svg`
+1. `/theme/themename/pix_core/i/user.jpg`
+
+For a more detailed description of how this all works see the page on [Using images in a theme](https://docs.moodle.org/dev/Using_images_in_a_theme).
diff --git a/versioned_docs/version-5.1/apis/plugintypes/theme/index.md b/versioned_docs/version-5.1/apis/plugintypes/theme/index.md
new file mode 100644
index 0000000000..509f70cafa
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/theme/index.md
@@ -0,0 +1,512 @@
+---
+title: Theme plugins
+tags:
+ - Plugins
+ - Theme
+---
+
+A Moodle theme allows users to customize the appearance and functionality of their Moodle site, from overall design to specific activities. Users can create their own themes or modify existing ones, leveraging CSS and JavaScript for customization. The theme architecture ensures smooth fallbacks for minimal changes, fostering flexibility and ease of use.
+
+## File structure
+
+import {
+ Lang,
+ Lib,
+ VersionPHP,
+} from '../../_files';
+
+Theme plugins are located in the `/theme` directory.
+
+Each plugin is in a separate subdirectory and consists of a number of _mandatory files_ and any other files the developer is going to use.
+
+/localcache/theme///css/all_.css
+```
+
+The cache path consists of a global theme revision (`themerev` config value) and a per theme sub-revision (`themesubrev` plugin config value). If either of those are incremented it will change the path to the cache file and cause a new file to be generated.
+
+Individual theme's CSS cache can be built by using the admin CLI script:
+
+```bash
+ php admin/cli/build_theme_css.php --themes boost
+```
+
+The script will only increment the theme sub-revision of the theme(s) being built which means existing theme cache's remain untouched.
+
+## See also
+
+
+
+- MoodleAcademy courses. For instance:
+ - [Moodle Page Layout and Site Navigation](https://moodle.academy/course/view.php?id=110)
+ - [Accessible Development Practices](https://moodle.academy/course/view.php?id=54)
+
+- MoodleBites Theme Design. Completely online courses [Level 1](https://www.moodlebites.com/mod/page/view.php?id=3208) and [Level 2](https://www.moodlebites.com/mod/page/view.php?id=3210) are designed to assist Moodle administrators, designers, and developers get up-to-speed with Moodle Theme design, and are run by [HRDNZ](https://www.hrdnz.com) (Certified Moodle Partner since 2006).
diff --git a/versioned_docs/version-5.1/apis/plugintypes/theme/layout.md b/versioned_docs/version-5.1/apis/plugintypes/theme/layout.md
new file mode 100644
index 0000000000..02a1a56898
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/theme/layout.md
@@ -0,0 +1,330 @@
+---
+title: Layout
+tags:
+ - Plugins
+ - Theme
+ - Layout
+sidebar_position: 1
+---
+
+All themes are required to define the layouts they wish to be responsible for as well as create; however, many layout files are required by those layouts. If the theme is overriding another theme then it is a case of deciding which layouts this new theme should override. If the theme is a completely fresh start then you will need to define a layout for each of the different possibilities.
+
+:::tip
+
+Note that a new theme that will base itself on another theme (overriding it) does not need to define any layouts or use any layout files if there are no changes that it wishes to make to the layouts of the existing theme.
+
+:::
+
+Layouts are defined in [`config.php`](../theme#configphp) within `$THEME->layouts`.
+
+The following is an example of one such layout definition:
+
+ {{{ sidepreblocks }}}
+
+ {{/hasblocks}}
+```
+
+When writing layout files, consider the variations in layouts and how the HTML utilized in each may differ. It is often unnecessary to create a distinct layout file for every layout; instead, existing layout files can often be reused across multiple layouts. Additionally, employing layout options can further minimize the need for creating additional layout files.
+
+It's important to note again that when customizing an existing theme, the creation of layouts or layout files may not be necessary.
+
+## Layout types
+
+- `base`. Most backwards compatible layout without the blocks. This is the layout used by default.
+- `standard`. Standard layout with blocks. This is recommended for most pages with general information.
+- `course`. Main course page.
+- `coursecategory`. Use for browsing through course categories.
+- `incourse`. Default layout while browsing a course, typical for modules.
+- `frontpage`. The site home page.
+- `admin`. Administration pages and scripts.
+- `mycourses`. My courses page.
+- `mydashboard`. My dashboard page.
+- `mypublic`. My public page.
+- `login`. The login page.
+- `popup`. Pages that appear in pop-up windows (no navigation, no blocks, no header).
+- `frametop`. Used for legacy frame layouts only. No blocks and minimal footer.
+- `embedded`. Used for embedded pages, like iframe/object embedded in moodleform. It needs as much space as possible.
+- `maintenance`. Used during upgrade and install. This must not have any blocks, and it is a good idea if it does not have links to other places. For example there should not be a home link in the footer.
+- `print`. Used when the page is being displayed specifically for printing.
+- `redirect`. Used when a redirection is occurring.
+- `report`. Used for reports.
+- `secure`. Used for `safebrowser` and `securewindow`.
diff --git a/versioned_docs/version-5.1/apis/plugintypes/theme/styles.md b/versioned_docs/version-5.1/apis/plugintypes/theme/styles.md
new file mode 100644
index 0000000000..bb8b26c81c
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/theme/styles.md
@@ -0,0 +1,136 @@
+---
+title: Styles
+tags:
+ - Plugins
+ - Theme
+ - Styles
+sidebar_position: 4
+---
+
+Let's begin by exploring the various locations within Moodle from which CSS can be included:
+
+- `\theme\themename\style\*.css`. This is the default location for all of the stylesheets that are used by a theme and the place which should be used by a theme designer if this theme is using CSS. Alternative to CSS is SCSS which is more powerful, flexible and easier to maintain.
+New theme developers should note that the order in which CSS files are found and included creates a hierarchy. This order ensures that the rules, within a theme's style sheets, take precedence over identical rules in other files that may have been introduced before. This can both extend another files definitions (see parent array in the config file) and also ensures that the current theme's CSS rules/definitions have the last say.
+There are other locations that can be used (although very rarely) to include CSS in a page. A developer of a php file can manually specify a stylesheet from anywhere within Moodle, like the database. Usually, if code is doing this, it is because there is a non-theme config or plugin setting that contains information requires special CSS information. As a theme designer you should be aware of, but not have to worry about, these locations of CSS files. Here are some examples: +- `{pluginpath}\styles.css` (for instance, `\block\blockname\styles.css` or `\mod\modname\styles.css`). Every plugin can have its own styles.css file. This file should only contain the required CSS rules for the module and should not add anything to the look of the plugin such as colours, font sizes, or margins other than those that are truly required.
Theme specific styles for a plugin should be located within the themes styles directory. +- `{pluginpath}\styles_themename.css`. This should only ever be used by plugin developers. It allows them to write CSS that is designed for a specific theme without having to make changes to that theme. You will notice that this is never used within Moodle and is designed to be used only by contributed code. + +:::tip + +As theme designers, only the first method of introducing CSS will be used: adding rules to a stylesheet file located in the theme's style directory. + +::: + +## CSS pre-processors + +Browsers understand CSS well, but it is hard to write and maintain. The language does not support inheritance and reuse. [Support for variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) exists in more modern browsers only. This is why CSS pre-processors were invented. Moodle supports SASS, which is recommended by far. + +:::info Information + +To use SASS, define `$THEME->scss = 'filename';` in your themes `config.php`. Moodle will then use one of it's in-built CSS pre-processor to compile the CSS the first time it is loaded (or every time if `themedesignermode` is enabled in `$CFG`). + +For more information see: [SASS (wikipedia)](https://en.wikipedia.org/wiki/Sass_(stylesheet_language)) + +::: + +## Core CSS organisation + +None of the themes provided in the standard install by Moodle use CSS stylesheets directly. Instead they use either SCSS to generate the style sheets. They all list one main SCSS file named `moodle` or scss folders and this file uses imports to load all other required files. + +:::note + +As a theme designer, it is entirely up to you how you create and organize your CSS and the rules you create. + +::: + +## How to write effective CSS rules within Moodle + +:::warning Important + +Writing good CSS rules is incredibly important. + +::: + +Due to performance requirements and browser limitations, all of the CSS files are combined into a single CSS file that gets included every time. This means that rules need to be written in such a way as to minimise the chances of a collision leading to unwanted styles being applied. Whilst writing good CSS is something most designers strive for we have implemented several new body classes and prompt developers to use appropriate classnames. + +### \ CSS id and classes
+
+The `ID` tag that gets applied to the body will always be a representation of the URI. For example if you are looking at a forum posting and the URI is `/mod/forum/view.php` then the body tags `ID` will be `#page-mod-forum-view`.
+
+As well as the body's ID attribute the URI is also exploded to form several CSS classes that get added to the body tag, so in the above example `/mod/forum/view` you would end up with the following classes being added to the body tag: `.path-mod` and `.path-mod-forum`.
+
+:::note
+
+`.path-mod-forum-view` is not added as a class, this is intentionally left out to lessen confusion and duplication as rules can relate directly to the page by using the ID and do not require the final class.
+
+:::
+
+The body ID and body classes described above will form the bread and butter for many of the CSS rules you will need to write for your theme, however there are also several other very handy classes that get added to the body tag that will be beneficial to you once you start your journey down the rabbit hole that is theming. Some of the more interesting classes are listed below.
+
+- If JavaScript is enabled then `jsenabled` will be added as a class to the body tag allowing you to style based on JavaScript being enabled or not.
+- Either `dir-rtl` or `dir-ltr` will be added to the body as a class depending on the direction of the language pack. This allows you to determine your text-alignment based on language if required:
+ - `rtl` = right to left
+ - `ltr` = left to right.
+- A class will be added to represent the language pack currently in use, by default `en_utf8` is used by Moodle and will result in the class `lang-en_utf8` being added to the body tag.
+- The `wwwroot` for Moodle will also be converted to a class and added to the body tag allowing you to stylise your theme based on the URL through which it was reached. For example, `http://sam.moodle.local/moodle/` will become `.sam-moodle-local—moodle`.
+- If the current user is not logged then `.notloggedin` will be added to the body tag.
+- The course format type will be added such as `format-weeks`.
+- The course id, context id and category id are all added as in `course-11 context-616 cmid-202 category-1`.
+- The `pagelayout` is added as `pagelayout-incourse`.
+
+:::info What does all of this look like in practise?
+
+Using the above example `/mod/forum/view.php` this will be the body tag:
+
+```html
+
+```
+
+:::
+
+### Writing your rules
+
+By following the [CSS coding style](https://docs.moodle.org/dev/CSS_coding_style) and CSS best-practices and understanding the [cascading order](http://htmlhelp.com/reference/css/structure.html#cascade) of CSS a theme developer will reduce collisions and lines of CSS that is written. CSS classes have been placed where it is believed anyone may want to apply their own styles.
+
+When starting to write rules make sure that you have a good understanding of where you want those rules to be applied, it is a good idea to make the most of the body classes mentioned above.
+
+- If you want to write a rule for a specific page make use of the body tag's ID:
+
+```css
+ #page-mod-forum-view .forumpost {
+ border: 1px solid blue;
+}
+```
+
+- If you want to write a rule that will be applied all throughout the forum:
+
+```css
+.path-mod-forum .forumpost {
+ border: 1px solid blue;
+}
+```
+
+The other very important thing to take into consideration is the structure leading up to the tag you want to style. Browsers apply conflicting styles with priority on the more specific selectors. It can be very beneficial to keep this in mind and write full selectors that rely on the structure of the tags leading to the tag you wish to style.
+
+By making use of body id's and classes and writing selectors to take into account the leading structure you can greatly minimise the chance of a collision both with Moodle now and in the future.
+
+:::tip
+
+It is also important to **write as FEW rules as possible**. CSS is extremely hard to maintain and lots of CSS is bad for client side performance.
+
+:::
+
+Themes based on the Bootstrap CSS framework can achieve most things without writing a single additional CSS rule. Please read [Bootstrap 4](https://getbootstrap.com/docs/4.0/getting-started/introduction/ the Bootstrap documentation) and learn how to use Bootstrap well to avoid adding unnecessary CSS rules for things already provided by the framework.
+
+## Compiling SCSS on the fly
+
+
+features:
+ settings: true
+privacy:
+ haspersonaldata: false
+ uselegacypolyfill: false
+tiny_features:
+ buttons:
+ - name: startdemo
+ category: content
+ text: Start demo
+ menuitems:
+ - name: startdemo
+ category: file
+ text: 'Start the demo'
+ options:
+ - name: myFirstProperty
+ type: string
+```
+
+### Generating the plugin skeleton
+
+Once you have created a plugin skeleton configuration, you can generate your plugin using the `cli/generate.php` command:
+
+```console
+php admin/tool/pluginskel/cli/generate.php tiny_example.yml
+```
+
+This will generate a working skeleton file for your plugin. Remember that you component name must start with `tiny_`.
+
+:::note Compiled JavaScript
+
+The plugin skeleton only produces source files for JavaScript. You will need to run `grunt` to compile this code.
+
+We highly recommend using `grunt watch` during development to simplify your workflow.
+
+```console
+cd lib/editor/tiny/plugins/example && npx grunt amd && cd -
+```
+
+:::
+
+## Key files
+
+There are a number of key files within the generated plugin skeleton, described below.
+
+### common.js
+
+The common.js file is used to store a set of variables used by other parts of the plugin.
+
+Its usage is optional, but recommended as it reduces code duplication, and the potential for typos and mistakes. It also makes it easier to refactor code later.
+
+
+ * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+if ($hassiteconfig) {
+ $ADMIN->add('localplugins', new admin_category('local_helloworld_settings', new lang_string('pluginname', 'local_helloworld')));
+ $settingspage = new admin_settingpage('managelocalhelloworld', new lang_string('manage', 'local_helloworld'));
+
+ if ($ADMIN->fulltree) {
+ $settingspage->add(new admin_setting_configcheckbox(
+ 'local_helloworld/showinnavigation',
+ new lang_string('showinnavigation', 'local_helloworld'),
+ new lang_string('showinnavigation_desc', 'local_helloworld'),
+ 1
+ ));
+ }
+
+ $ADMIN->add('localplugins', $settingspage);
+}
+```
+
+Few things to highlight:
+
+- Note the variable $hassiteconfig which can be used as a quick way to check for the moodle/site:config permission. This variable is set by the top-level admin tree population scripts.
+- We always add the custom admin_settingpage to the tree, but the actual settings are added to that page only when $ADMIN->fulltree is set. This is to improve performance when the caller does not need the actual settings but only the administration pages structure.
+- The lang_string class instances are used as proxy objects to represent strings. This has performance benefits as there is no need to evaluate all strings in the admin settings tree unless they are actually displayed.
+
+## Individual settings
+
+Let us look at a simple example: [mod/lesson/settings.php](https://github.com/moodle/moodle/blob/main/mod/lesson/settings.php). This is included by admin/settings/plugins.php, which has already created $settings, which is an admin_settingpage that we can add to. The file contains lots of lines that look a bit like:
+
+```php
+$settings->add(new admin_setting_configtext('mod_lesson/mediawidth', get_string('mediawidth', 'lesson'),
+ get_string('configmediawidth', 'lesson'), 640, PARAM_INT));
+```
+
+What this means is that to our settings page, we are adding a text setting. To understand this in more detail, we need to know what arguments the constructor for this admin_setting_configtext takes. The signature of the constructor is:
+
+```php
+public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $size=null)
+```
+
+- $name here is 'mod_lesson/mediawidth'. The slash is important here. It indicates that this setting is owned by the mod_lesson plugin and should be stored in the config_plugins table. Settings that do not have this slash would be stored in the global config table and also exposes them via $CFG properties. Plugin-scope settings can be obtained only via get_config() call. You may notice some older plugins such as the Forum module or many blocks, still store their settings in the global config table. That is strongly discouraged for new plugins.
+- $visiblename is set to a string get_string('mediawidth', 'lesson'), this is the label that is put in front of setting on the admin screen.
+- $description is set to another string, this is a short bit of text displayed underneath the setting to explain it further. Older plugins used strings prefixed with "config" for this purpose. The current best practice is to use "_desc" prefix for them - see [String API#Help strings](https://docs.moodle.org/dev/String_API#Help_strings)
+- $defaultsetting is the default value for this setting. This value is used when Moodle is installed. For simple settings like checkboxes and text fields, this is a simple value. For some more complicated settings, this is an array.
+- $paramtype is one of the constants describing the type of the input text. The inserted value will be sanitised according to the declared type.
+- $size allows to specify custom size of the field in the user interface
+
+Let us now look at a more complicated example, from mod/quiz/settingstree.php:
+
+```php
+ $quizsettings->add(new admin_setting_text_with_advanced('quiz/timelimit', get_string('timelimit', 'quiz'), get_string('timelimit_desc', 'quiz'),
+ ['value' => '0', 'fix' => false], PARAM_INT));
+```
+
+*Note:* the naming convention used here is slightly outdated; new activity modules should use 'mod_mymodule/setting' instead of 'mymodule/setting' as identifier.
+
+This example shows a $defaultsetting that is an array.
+
+Normally, if you want a particular sort of setting, the easiest way is to look around the admin screens of your Moodle site, and find a setting like the one you want. Then go and copy the code and edit it. Therefore, we do not include a complete list of setting types here.
+
+## Locked and advanced settings for activity modules
+
+Admin settings are often used to define the defaults for activity settings. There is a simple way to enable admins make activity settings as "locked" (cannot be changed from the default) or "advanced" (deprecated, used before the change to "short forms").
+
+When creating the admin setting (e.g. in mod/assign/settings.php), create the setting like this:
+
+```php
+$name = new lang_string('teamsubmission', 'mod_assign');
+$description = new lang_string('teamsubmission_help', 'mod_assign');
+$setting = new admin_setting_configcheckbox('assign/teamsubmission',
+ $name,
+ $description,
+ 1);
+$setting->set_advanced_flag_options(admin_setting_flag::ENABLED, false);
+$setting->set_locked_flag_options(admin_setting_flag::ENABLED, false);
+$settings->add($setting);
+```
+
+To add "locked" and "advanced" check boxes to the admin setting.
+
+And finally, when creating the activity form (e.g. in mod/assign/mod_form.php), call this:
+
+```php
+$this->apply_admin_defaults();
+```
+
+at the end of the constructor to automatically set the default and lock the form element if required.
+
+Note: Locking an admin setting **will not force the value on existing settings*. Activity settings that are locked will need to be manually updated if they differ from the locked default value.
+
+## Callbacks after a setting has been updated
+
+A typical example is purging a cache after a setting has changed:
+
+```php
+$setting = new admin_setting_configcheckbox(......);
+$setting->set_updatedcallback('theme_reset_all_caches');
+```
+
+## External pages
+
+admin_externalpages represent screens of settings that do not fall into the standard pattern of admin_settings. The admin_externalpage object in the settings tree holds the URL of a PHP page that controls various settings.
+
+In that PHP page, near the start you need to call the function admin_externalpage_setup($pagename). Although earlier versions of Moodle required you to then use admin_externalpage_print_header() and admin_externalpage_print_footer() functions instead of the usual print_header and print_footer functions, this is no longer necessary as of Moodle 2.0 - just use $OUTPUT->header() and $OUTPUT->footer() as per usual (don't forget to echo them). This ensures that your page appears with the administration blocks and appropriate navigation.
+
+Note that if your external page relies on additional optional or required params, you may need to use the optional arguments to admin_externalpage_print_header to ensure that the Blocks editing on/off button works.
+
+Note that there are some subclasses of admin_externalpage, for example admin_page_managemods. In a lot of cases, these subclasses only exist to override the search method so this page can be found by appropriate searches.
+
+Once again, to understand this in more depth, your best approach is to look at how some of the external pages in Moodle work.
+
+### When to use an admin_settings vs admin_externalpages
+
+The short answer is wherever possible always try to use admin settings rather than a custom page which uses formslib for anything related to admin settings. If you need something custom investigate a custom admin_setting class before a custom external page. There are a number of reasons, some around usability but mostly related to security:
+
+- **Searching** - Admin settings can be searched for using the admin search, while only the page title of the external page is searchable. In particular it is very useful to search directly for the key name of a config item, but also the settings current value and it's help text. Also the admin settings tree is a public API and there are 3rd party plugins which leverage this for various purposes, so your settings will be invisible.
+- **Manage from CLI** - All admin settings in core and plugins can be managed via admin/cli/cfg.php, you don't get this for free if you store settings manually in a custom table.
+- **Caching** - All admin settings in core and plugins are cached in the MUC and you don't get this for free if you store settings manually in a custom table.
+- **Forced settings** - Normal admin settings can be forced in config.php and this is shown as forced in the GUI. Unless you re-implement this forced logic admins will get the false impression they are saving a setting when they are won't and it will cause a lot of confusion.
+- **Forced passwords** - Password admin settings can be forced in config.php and these are not only locked but hidden from the admin (since Moodle 3.9). You would have to, and should, re-implement this logic on top of the 'forced' logic above.
+- **Executable paths** - A special case of forced settings is paths to executables which should ideally be set in config.php with $CFG->preventexecpath = true; so they cannot be set in the GUI, even if they aren't in config.php. The admin_setting_configexecutable class handles all this logic for you.
+- **Config log** - When an admin setting is changed, the before and after values are appended to the config log and visible in the config changes report. If you ever call set_config directly on behalf of a human, you should call add_to_config_log as well. It is really important to have a strong audit trail of who did what. For normal actions by anyone this should be in the moodle log, for admin settings it should be in the config log.
+
+An OK rule of thumb is: You can use an external page, which might use formslib, when the settings you are changing are in a custom table and not in the config tables via set_config. But you should seriously consider if and why you need a custom table first. If you are writing custom formslib elements it is usually just as easy to write a custom admin_setting instead.
+
+## See also
+
+- [adding settings for activity modules](https://docs.moodle.org/dev/Modules)
+- [adding admin reports to the tree](https://docs.moodle.org/dev/Admin_reports#How_your_report_gets_included_in_the_admin_tree)
+- configuration of repository plugins
+- [configuration for filter](../../plugintypes/filter/index.md)
+- [Other developer documentation](https://docs.moodle.org/dev/Developer_documentation)
diff --git a/versioned_docs/version-5.1/apis/subsystems/ai/index.md b/versioned_docs/version-5.1/apis/subsystems/ai/index.md
new file mode 100644
index 0000000000..297f2907f2
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/ai/index.md
@@ -0,0 +1,291 @@
+---
+title: AI Subsystem
+tags:
+ - AI
+ - LLM
+ - Provider
+ - Placement
+---
+
+_`.
+
+#### Actions in AI subsystem
+
+- `generate_image`
+- `generate_text`
+- `summarise_text`
+
+#### Base abstract class
+
+Each Action **must** inherit from the `\core_ai\aiactions\base` abstract class.
+They must also implement two methods:
+
+##### 1. `__construct()`
+
+- The constructor method is allowed to have a variable signature, so that each Action can define its own
+configuration requirements.
+- The method **must** take a `contextid` as one of the variables.
+- An Action **must** be correctly instantiated before it can be used and passed to the AI manager.
+
+```php title="Example: The __construct() method for the generate_image Action"
+public function __construct(
+ int $contextid,
+ /** @var int The user id requesting the action. */
+ protected int $userid,
+ /** @var string The prompt text used to generate the image */
+ protected string $prompttext,
+ /** @var string The quality of the generated image */
+ protected string $quality,
+ /** @var string The aspect ratio of the generated image */
+ protected string $aspectratio,
+ /** @var int The number of images to generate */
+ protected int $numimages,
+ /** @var string The visual style of the generated image */
+ protected string $style,
+) {
+ parent::__construct($contextid);
+}
+```
+
+##### 2. `store()`
+
+- This method is responsible for storing data related to the Action in the LMS database.
+- Each Action must store its own data that can be referenced later.
+- It takes a matching response class that contains the result of the Action call.
+
+```php title="Example: The store() method for the generate_image Action"
+#[\Override]
+public function store(response_base $response): int {
+ global $DB;
+
+ $responsearr = $response->get_response_data();
+
+ $record = new \stdClass();
+ $record->prompt = $this->prompttext;
+ $record->numberimages = $this->numimages;
+ $record->quality = $this->quality;
+ $record->aspectratio = $this->aspectratio;
+ $record->style = $this->style;
+ $record->sourceurl = $responsearr['sourceurl']; // Can be null.
+ $record->revisedprompt = $responsearr['revisedprompt']; // Can be null.
+
+ return $DB->insert_record($this->get_tablename(), $record);
+}
+```
+
+Each Action will need to define its own database schema and stored data that is relevant to what it does.
+
+```xml title="Example: The database table definition for the generate_image Action"
+
+
+```
+
+The naming convention for Action database tables is `ai_action_`. For example: `ai_action_generate_image`, `ai_action_translate_text`.
+
+#### Pre-defined Models
+
+We can define a set of models that are available for the Actions of the Providers.
+See the [Pre-defined Models](/apis/plugintypes/ai/provider.md#predefined-models) documentation for more information
+on developing Pre-defined Models for Provider plugins.
+
+#### Responses
+
+When a Provider processes an Action it **must** return a response object.
+This allows Placements to receive an expected response for any Action call.
+Each Action has a matching response class. The Provider that processes the Action will instantiate
+an instance of this response class and populate it with the data required for this type of response.
+
+Each Action response **must** inherit from the `\core_ai\aiactions\responses\response_base` abstract
+class. They must also implement two methods:
+
+##### 1. `set_response_data()`
+
+Taking an array of response variables (which must be defined as class variables),
+it sets these against class variables so they can be retrieved by the Manager and calling Placement.
+
+```php title="Example: The set_response_data() for the generate_image Action response"
+ #[\Override]
+ public function set_response_data(array $response): void {
+ $this->draftfile = $response['draftfile'] ?? null;
+ $this->revisedprompt = $response['revisedprompt'] ?? null;
+ $this->sourceurl = $response['sourceurl'] ?? null;
+ }
+```
+
+##### 2. `get_response_data()`
+
+Returns the set response data.
+
+```php title="Example: The get_response_data() for the generate_image Action response"
+ #[\Override]
+ public function get_response_data(): array {
+ return [
+ 'draftfile' => $this->draftfile,
+ 'revisedprompt' => $this->revisedprompt,
+ 'sourceurl' => $this->sourceurl,
+ ];
+ }
+```
+
+The naming convention for Action response classes is `response_`. For example: `response_generate_image`, `response_translate_text`.
+
+## AI User Policy
+
+Inline with Moodle's AI Principles, and as guided by emerging legislation, users must accept the
+AI User Policy before using AI in LMS. As the requirements are different from a site policy,
+separate policy functionality has been implemented for the AI subsystem (legislation indicates acknowledgement of AI must be made at point of use).
+
+- Placements must implement a check to see if a user has accepted the policy.
+- Placements must provide a way for users to accept the policy.
+- If a user has not previously accepted the policy, the Placement must display the policy to the user.
+- The user is not able to use the Placement until they accept the policy.
+- Users only need to accept the policy once.
+
+To assist Placements with displaying the AI User Policy, the Manager provides the following functionality:
+
+### Direct call
+
+The Manager makes the following methods available for Placements to call directly:
+
+#### `\core_ai\manager::get_user_policy_status(int $userid): bool`
+
+Given a User ID (record id in user table), returns `true` if the user has accepted the policy,
+`false` otherwise. It handles looking up the status and caching the response.
+
+#### `\core_ai\manager::user_policy_accepted(int $userid, int $contextid): bool`
+
+Given a User ID and a Context ID (context the policy was displayed in), set the policy
+acceptance.
+
+### Webservices
+
+The Manager class also makes available webservices to be used for policy setting and getting.
+This helps Placements set policy acceptance via Ajax as part of a UI workflow:
+
+#### `core_ai_get_policy_status`
+
+Gets the policy status for a user. Calls: `core_ai\external\get_policy_status`
+
+#### `core_ai_set_policy_status`
+
+Sets the policy status for a user. Calls: `core_ai\external\set_policy_status`
diff --git a/versioned_docs/version-5.1/apis/subsystems/analytics/_index/Analytics_API_classes_diagram_(summary).svg b/versioned_docs/version-5.1/apis/subsystems/analytics/_index/Analytics_API_classes_diagram_(summary).svg
new file mode 100644
index 0000000000..e6bbbfdd35
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/analytics/_index/Analytics_API_classes_diagram_(summary).svg
@@ -0,0 +1,4 @@
+
+
+
+
diff --git a/versioned_docs/version-5.1/apis/subsystems/analytics/_index/Inspire_API_components.png b/versioned_docs/version-5.1/apis/subsystems/analytics/_index/Inspire_API_components.png
new file mode 100644
index 0000000000..976d1d72cb
Binary files /dev/null and b/versioned_docs/version-5.1/apis/subsystems/analytics/_index/Inspire_API_components.png differ
diff --git a/versioned_docs/version-5.1/apis/subsystems/analytics/_index/Inspire_data_flow.png b/versioned_docs/version-5.1/apis/subsystems/analytics/_index/Inspire_data_flow.png
new file mode 100644
index 0000000000..915a745aee
Binary files /dev/null and b/versioned_docs/version-5.1/apis/subsystems/analytics/_index/Inspire_data_flow.png differ
diff --git a/versioned_docs/version-5.1/apis/subsystems/analytics/index.md b/versioned_docs/version-5.1/apis/subsystems/analytics/index.md
new file mode 100644
index 0000000000..8a9f9b28f6
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/analytics/index.md
@@ -0,0 +1,812 @@
+---
+title: Analytics API
+description: The Analytics API allows managers to use predictions to detect trends and predict student behaviour
+tags:
+ - Analytics
+ - API
+---
+
+
+
+The Moodle Analytics API allows Moodle site managers to define _prediction models_ that combine _indicators_ and a _target_.
+
+The _target_ is the event we want to predict. The _indicators_ are what we think will lead to an accurate prediction of the target.
+
+Moodle is able to evaluate these models and, if the prediction accuracy is high enough, Moodle internally trains a machine learning algorithm by using calculations based on the defined indicators within the site data. Once new data that matches the criteria defined by the model is available, Moodle starts predicting the probability that the target event will occur. Targets are free to define what actions will be performed for each prediction, from sending messages or feeding reports to building new adaptive learning activities.
+
+:::note Example
+
+An example of a model you may be interested in is the detection of [students who are at risk of dropping out](https://docs.moodle.org/en/Students_at_risk_of_dropping_out).
+
+Possible _indicators_ for this include:
+
+- a lack of participation in previous activities
+- poor grades in previous activities
+
+The _target_ would be whether the student is able to complete the course or not.
+
+Moodle uses these indicators and the target for each student in a finished course to predict which students are at risk of dropping out in ongoing courses.
+
+:::
+
+## Summary
+
+### API components
+
+This diagram shows the main components of the analytics API and the interactions between them.
+
+
+
+### Data flow
+
+The diagram below shows the different stages data goes through, from the data a Moodle site contains to actionable insights.
+
+
+
+### API classes diagram
+
+This is a summary of the API classes and their relationships. It groups the different parts of the framework that can be extended by 3rd parties to create your own prediction models.
+
+.svg)
+
+## Built-in models
+
+People use Moodle in very different ways and even courses on the same site can vary significantly. Moodle core only includes models that have been proven to be good at predicting in a wide range of sites and courses. Moodle provides two built-in models:
+
+- [Students at risk of dropping out](https://docs.moodle.org/en/Students_at_risk_of_dropping_out)
+- [No teaching](https://docs.moodle.org/en/Analytics#No_teaching)
+
+To diversify the samples and to cover a wider range of cases, the Moodle HQ research team is collecting anonymised Moodle site datasets from collaborating institutions and partners to train the machine learning algorithms with them. The models that Moodle is shipped with will be likely better at predicting on the sites of participating institutions, although some other datasets are used as test data for the machine learning algorithm to ensure that the models are good enough to predict accurately in any Moodle site.
+
+Even if the models included in Moodle core are already trained by Moodle HQ, each different site will continue training that site machine learning algorithms with its own data, which will lead to better prediction accuracy over time.
+
+## Concepts
+
+The following definitions are included for people not familiar with machine learning concepts:
+
+### Training
+
+This is the process to be run on a Moodle site before being able to predict anything. This process records the relationships found in site data from the past so the analytics system can predict what is likely to happen under the same circumstances in the future. What we train are machine learning algorithms.
+
+### Samples
+
+The machine learning backends we use to make predictions need to know what sort of patterns to look for, and where in the Moodle data to look. A sample is a set of calculations we make using a collection of Moodle site data. These samples are unrelated to testing data or phpunit data, and they are identified by an id matching the data element on which the calculations are based. The id of a sample can be any Moodle entity id: a course, a user, an enrolment, a quiz attempt, etc. and the calculations the sample contains depend on that element. Each type of Moodle entity used as a sample helps develop the predictions that involve that kind of entity. For example, samples based on Quiz attempts will help develop the potential insights that the analytics might offer that are related to the Quiz attempts by a particular group of students. See the [Analyser](#analyser) documentation for more information on how to use analyser classes to define what is a sample.
+
+### Prediction model
+
+As explained above, a prediction model is a combination of indicators and a target. System models can be viewed in **Site administration > Analytics > Analytics models**.
+
+The relationship between indicators and targets is stored in *analytics_models* database table.
+
+The class `\core_analytics\model` manages all of a model's related actions. *evaluate()*, *train()* and *predict()* forward the calculated indicators to the machine learning backends. `\core_analytics\model` delegates all heavy processing to analysers and machine learning backends. It also manages prediction models evaluation logs.
+
+`\core_analytics\model` class is not expected to be extended.
+
+#### Static models
+
+Some prediction models do not need a powerful machine learning algorithm behind them processing large quantities of data to make accurate predictions. There are obvious events that different stakeholders may be interested in knowing that we can easily calculate. These *Static model* predictions are directly calculated based on indicator values. They are based on the assumptions defined in the target, but they should still be based on indicators so all these indicators can still be reused across different prediction models. For this reason, static models are not editable through **Site administration > Analytics > Analytics models** user interface.
+
+Some examples of possible static models:
+
+- [Courses without teaching activity](https://docs.moodle.org/en/Analytics#No_teaching)
+- Courses with students submissions requiring attention and no teachers accessing the course
+- Courses that started 1 month ago and never accessed by anyone
+- Students that have never logged into the system
+
+Moodle can already generate notifications for the examples above, but there are some benefits on doing it using the Moodle analytics API:
+
+- Everything is easier and faster to code from a development point of view as the analytics subsystem provides APIs for everything
+- New Indicators will be part of the core indicators pool that researchers (and 3rd party developers in general) can reuse in their own models
+- Existing core indicators can be reused as well (the same indicators used for insights that depend on machine learning backends)
+- Notifications are displayed using the core insights system, which is also responsible of sending the notifications and all related actions.
+- The Analytics API tracks user actions after viewing the predictions, so we can know if insights result in actions, which insights are not useful, etc. User responses to insights could themselves be defined as an indicator.
+
+### Analyser
+
+Analysers are responsible for creating the dataset files that will be sent to the machine learning processors. They are coded as PHP classes. Moodle core includes some analysers that you can use in your models.
+
+The base class `\core_analytics\local\analyser\base` does most of the work. It contains a key abstract method, *get_all_samples()*. This method is what defines the sample unique identifier across the site. Analyser classes are also responsible of including all site data related to that sample id; this data will be used when indicators are calculated. e.g. A sample id *user enrolment* would include data about the *course*, the course *context* and the *user*. Samples are nothing by themselves, just a list of ids with related data. They are used in calculations once they are combined with the target and the indicator classes.
+
+Other analyser class responsibilities:
+
+- Define the context of the predictions
+- Discard invalid data
+- Filter out already trained samples
+- Include the time factor (time range processors, explained below)
+- Forward calculations to indicators and target classes
+- Record all calculations in a file
+- Record all analysed sample ids in the database
+
+If you are introducing a new analyser, there is an important non-obvious fact you should know about: for scalability reasons, all calculations at course level are executed in per-course basis and the resulting datasets are merged together once all site courses analysis is complete. This is for performance reasons: depending on the sites' size it could take hours to complete the analysis of the entire site. This is a good way to break the process up into pieces. When coding a new analyser you need to decide if you want to extend `\core_analytics\local\analyser\by_course` (your analyser will process a list of courses), `\core_analytics\local\analyser\site-wide` (your analyser will receive just one analysable element, the site) or create your own analyser for activities, categories or any other Moodle entity.
+
+### Target
+
+Targets are the key element that defines the model. As a PHP class, targets represent the event the model is attempting to predict (the [dependent variable in supervised learning](https://en.wikipedia.org/wiki/Dependent_and_independent_variables)). They also define the actions to perform depending on the received predictions.
+
+Targets depend on analysers, because analysers provide them with the samples they need. Analysers are separate entities from targets because analysers can be reused across different targets. Each target needs to specify which analyser it is using. Here are a few examples to clarify the difference between analysers, samples and targets:
+
+- **Target**: 'students at risk of dropping out'. **Analyser provides sample**: 'course enrolments'
+- **Target**: 'spammer'. **Analyser provides sample**: 'site users'
+- **Target**: 'ineffective course'. **Analyser provides sample**: 'courses'
+- **Target**: 'difficulties to pass a specific quiz'. **Analyser provides sample**: 'quiz attempts in a specific quiz'
+
+A callback defined by the target will be executed once new predictions start coming so each target have control over the prediction results.
+
+The API supports binary classification, multi-class classification and regression, but the machine learning backends included in core do not yet support multi-class classification or regression, so only binary classifications will be initially fully supported. See [MDL-59044](https://moodle.atlassian.net/browse/MDL-59044) and [MDL-60523](https://moodle.atlassian.net/browse/MDL-60523) for more information.
+
+Although there is no technical restriction against using core targets in your own models, in most cases each model will implement a new target. One possible case in which targets might be reused would be to create a new model using the same target and a different sets of indicators, for A/B testing
+
+#### Insights
+
+Another aspect controlled by targets is insight generation. Insights represent predictions made about a specific element of the sample within the context of the analyser model. This context will be used to notify users with the `moodle/analytics:listinsights` capability (the teacher role by default) about new insights being available. These users will receive a notification with a link to the predictions page where all predictions of that context are listed.
+
+A set of suggested actions will be available for each prediction. In cases like *[Students at risk of dropping out](https://docs.moodle.org/en/Students_at_risk_of_dropping_out)* the actions can be things like sending a message to the student, viewing the student's course activity report, etc.
+
+### Indicator
+
+Indicator PHP classes are responsible for calculating indicators (predictor value or [independent variable in supervised learning](https://en.wikipedia.org/wiki/Dependent_and_independent_variables)) using the provided sample. Moodle core includes a set of indicators that can be used in your models without additional PHP coding (unless you want to extend their functionality).
+
+Indicators are not limited to a single analyser like targets are. This makes indicators easier to reuse in different models. Indicators specify a minimum set of data they need to perform the calculation. The indicator developer should also make an effort to imagine how the indicator will work when different analysers are used. For example an indicator named *Posts in any forum* could be initially coded for a *Shy students in a course* target; this target would use *course enrolments* analyser, so the indicator developer knows that a *course* and an *enrolment* will be provided by that analyser, but this indicator can be easily coded so the indicator can be reused by other analysers like *courses* or *users'. In this case the developer can chose to require *course* **or** *user*, and the name of the indicator would change according to that. For example, *User posts in any forum* could be used in a user-based model like *Inactive users* and in any other model where the analyser provides *user* data; *Posts in any of the course forums* could be used in a course-based model like *Low participation courses.''
+
+The calculated value can go from -1 (minimum) to 1 (maximum). This requirement prevents the creation of "raw number" indicators like *absolute number of write actions,* because we must limit the calculation to a range, e.g. -1 = 0 actions, -0.33 = some basic activity, 0.33 = activity, 1 = plenty of activity. Raw counts of an event like "posts to a forum" must be calculated in a proportion of an expected number of posts. There are several ways of doing this. One is to define a minimum desired number of events, e.g. 3 posts in a forum represents "some" activity, 6 posts represents adequate activity, and 10 or more posts represents the maximum expected activity. Another way is to compare the number of events per individual user to the mean or median value of events by all users in the same context, using statistical values. For example, a value of 0 would represent that the student posted the same number of posts as the mean of all student posts in that context; a value of -1 would indicate that the student is 2 or 3 standard deviations below the mean, and a +1 would indicate that the student is 2 or 3 standard deviations above the mean.
+
+:::danger Comparative rankings
+
+This kind of comparative calculation has implications to pedagogy: it suggests that there is a ranking of students from best to worst, rather than a defined standard all students can reach. Please be aware of this when considering how indicators are presented to users.
+
+:::
+
+### Analysis intervals
+
+Analysis intervals define when the system will calculate predictions and the portion of activity logs that will be considered for those predictions. They are coded as PHP classes and Moodle core includes some analysis intervals you can use in your models.
+
+:::info Time-splitting methods
+
+Analysis intervals were previously known as Time-splitting methods.
+
+:::
+
+In some cases the time factor is not important and we just want to classify a sample. This is relatively simple. Things get more complicated when we want to predict what will happen in future. For example, predictions about [Students at risk of dropping out](https://docs.moodle.org/en/Students_at_risk_of_dropping_out) are not useful once the course is over or when it is too late for any intervention.
+
+Calculations involving time ranges can be a challenging aspect of some prediction models. Indicators need to be designed with this in mind and we need to include time-dependent indicators within the calculated indicators so machine learning algorithms are smart enough to avoid mixing calculations belonging to the beginning of the course with calculations belonging to the end of the course.
+
+There are many different ways to split up a course into time ranges: in weeks, quarters, 8 parts, ten parts (tenths), ranges with longer periods at the beginning and shorter periods at the end... And the ranges can be accumulative (each one inclusive from the beginning of the course) or only from the start of the time range.
+
+Many of the analysis intervals included in Moodle assume that there is a fixed start and end date for each course, so the course can be divided into segments of equal length. This allows courses of different lengths to be included in the same prediction model, but makes these analysis intervals useless for courses without fixed start or end dates, e.g. self-paced courses. These courses might instead use fixed time lengths such as weeks to define the boundaries of prediction calculations.
+
+### Machine learning backends
+
+Documentation available in [Machine learning backends](../../plugintypes/mlbackend/index.md).
+
+## Design
+
+The system is designed as a Moodle subsystem and API. It lives in `analytics/`. All analytics base classes are located here.
+
+[Machine learning backends](../../plugintypes/mlbackend/index.md) is a new Moodle plugin type. They are stored in `lib/mlbackend`.
+
+Uses of the analytics API are located in different Moodle components, being core (`lib/classes/analytics`) the component that hosts general purpose uses of the API.
+
+### Interfaces
+
+This API aims to be as extendable as possible. Any moodle component, including third party plugins, is able to define indicators, targets, analysers and time splitting methods. Analytics API will be able to find them as long as they follow the namespace conventions described below.
+
+An example of a possible extension would be a plugin with indicators that fetch student academic records from the Universities' student information system; the site admin could build a new model on top of the built-in 'students at risk of drop out detection' adding the SIS indicators to improve the model accuracy or for research purposes.
+
+:::note Machine learning backends
+
+This section does not include Machine learning backend interfaces. See [Machine learning backends](../../plugintypes/mlbackend/index.md#interfaces) for more information on these.
+
+:::
+
+#### Analysable (core_analytics\analysable)
+
+Analysables are those elements in Moodle that contain samples. In most of the cases an analysable will be a course, although it can also be the site or any other Moodle element, e.g. an activity. Moodle core includes two analysers `\core_analytics\course` and `\core_analytics\site`.
+
+They list of methods that need to be implemented is quite simple and does not require much explanation.
+
+:::danger
+
+Analysable elements should be lazily loaded, otherwise you may encounter PHP memory issues. The reason is that analysers load all analysable elements in the site to calculate which ones are going to be calculated next (skipping the ones processed recently and stuff like that).
+
+See `core_analytics\course` as an example of how this can be achieved.
+
+:::
+
+Methods to implement:
+
+```php
+/**
+ * The analysable unique identifier in the site.
+ *
+ * @return int.
+ */
+public function get_id();
+
+/**
+ * The analysable human readable name
+ *
+ * @return string
+ */
+public function get_name();
+
+/**
+ * The analysable context.
+ *
+ * @return \context
+ */
+public function get_context();
+```
+
+`get_start` and `get_end` define the start and end times that indicators will use for their calculations.
+
+```php
+/**
+ * The start of the analysable if there is one.
+ *
+ * @return int|false
+ */
+public function get_start();
+
+/**
+ * The end of the analysable if there is one.
+ *
+ * @return int|false
+ */
+public function get_end();
+```
+
+#### Analyser (core_analytics\local\analyser\base)
+
+The get_analysables() method has been deprecated in favour of a new `get_analysables_iterator()` for performance reasons. This method returns the whole list of analysable elements in the site. Each model will later be able to discard analysables that do not match their expectations. *e.g. if your model is only interested in quizzes with a time close the analyser will return all quizzes, your model will exclude the ones without a time close. This approach is supposed to make analysers more reusable.*
+
+```php
+/**
+ * Returns the list of analysable elements available on the site.
+ *
+ * A relatively complex SQL query should be set so that we take into account which analysable elements
+ * have already been processed and the order in which they have been processed. Helper methods are available
+ * to ease to implementation of get_analysables_iterator: get_iterator_sql and order_sql.
+ *
+ * @param string|null $action 'prediction', 'training' or null if no specific action needed.
+ * @return \Iterator
+ */
+public function get_analysables_iterator(?string $action = null)
+```
+
+`get_all_samples` and `get_samples` should return data associated with the sample ids they provide. This is important for 2 reasons:
+
+- The data they provide alongside the sample origin is used to filter out indicators that are not related to what this analyser analyses. ''e.g. courses analysers do provide courses and information about courses, but not information about users, a **is user profile complete** indicator will require the user object to be available. A model using a courses analyser will not be able to use the **is user profile complete** indicator.
+- The data included here is cached in PHP static vars; on one hand this reduces the amount of db queries indicators need to perform. On the other hand, if not well balanced, it can lead to PHP memory issues.
+
+```php
+/**
+ * This function returns this analysable list of samples.
+ *
+ * @param \core_analytics\analysable $analysable
+ * @return array array[0] = int[] (sampleids) and array[1] = array (samplesdata)
+ */
+abstract public function get_all_samples(\core_analytics\analysable $analysable);
+```
+
+```php
+/**
+ * This function returns the samples data from a list of sample ids.
+ *
+ * @param int[] $sampleids
+ * @return array array[0] = int[] (sampleids) and array[1] = array (samplesdata)
+ */
+abstract public function get_samples($sampleids);
+```
+
+`get_sample_analysable` method is executing during prediction:
+
+```php
+/**
+ * Returns the analysable of a sample.
+ *
+ * @param int $sampleid
+ * @return \core_analytics\analysable
+ */
+abstract public function get_sample_analysable($sampleid);
+```
+
+The sample origin is the moodle database table that uses the sample id as primary key.
+
+```php
+/**
+ * Returns the sample's origin in moodle database.
+ *
+ * @return string
+ */
+abstract public function get_samples_origin();
+```
+
+`sample_access_context` associates a context to a `sampleid`. This is important because this sample predictions will only be available for users with `moodle/analytics:listinsights` capability in that context.
+
+```php
+/**
+ * Returns the context of a sample.
+ *
+ * @param int $sampleid
+ * @return \context
+ */
+abstract public function sample_access_context($sampleid);
+```
+
+`sample_description` is used to display samples in *Insights* report:
+
+```php
+/**
+ * Describes a sample with a description summary and a \renderable (an image for example)
+ *
+ * @param int $sampleid
+ * @param int $contextid
+ * @param array $sampledata
+ * @return array array(string, \renderable)
+ */
+abstract public function sample_description($sampleid, $contextid, $sampledata);
+```
+
+`processes_user_data` and `join_sample_user` methods are used by the analytics implementation of the privacy API. You only need to overwrite them if your analyser deals with user data. They are used to export and delete user data that is stored in analytics database tables:
+
+```php
+/**
+ * Whether the plugin needs user data clearing or not.
+ *
+ * @return bool
+ */
+public function processes_user_data();
+```
+
+```php
+/**
+ * SQL JOIN from a sample to users table.
+ *
+ * More info in [https://github.com/moodle/moodle/blob/main/analytics/classes/local/analyser/base.php core_analytics\local\analyser\base]::join_sample_user
+ *
+ * @param string $sampletablealias The alias of the table with a sampleid field that will join with this SQL string
+ * @return string
+ */
+public function join_sample_user($sampletablealias);
+```
+
+You can overwrite a `new one_sample_per_analysable()` method if the analysables your model is using only have one sample. The insights generated by models will then include the suggested actions in the notification.
+
+```php
+/**
+ * Just one sample per analysable.
+ *
+ * @return bool
+ */
+public static function one_sample_per_analysable() {
+ return true;
+}
+```
+
+#### Indicator (core_analytics\local\indicator\base)
+
+Indicators should generally extend one of these 3 classes, depending on the values they can return: *core_analytics\local\indicator\binary* for **yes/no** indicators, *core_analytics\local\indicator\linear* for indicators that return linear values and *core_analytics\local\indicator\discrete* for categorised indicators. In case you want your activity module to implement a [community of inquiry](https://docs.moodle.org/en/Students_at_risk_of_dropping_out#Indicators) indicator you can extend *core_analytics\local\indicator\community_of_inquiry_indicator* look for examples in Moodle core.
+
+You can use `required_sample_data` to specify what your indicator needs to be calculated; you may need a *user* object, a *course*, a *grade item*... The default implementation does not require anything. Models which analysers do not return the required data will not be able to use your indicator so only list here what you really need. e.g. if you need a grade_grades record mark it as required, but there is no need to require the *user* object and the *course* as well because you can obtain them from the grade_grades item. It is very likely that the analyser will provide them as well because the principle they follow is to include as much related data as possible but do not flag related objects as required because an analyser may, for example, chose to not include the *user* object because it is too big and sites can have memory problems.
+
+```php
+/**
+ * Allows indicators to specify data they need.
+ *
+ * e.g. A model using courses as samples will not provide users data, but an indicator like
+ * "user is hungry" needs user data.
+ *
+ * @return null|string[] Name of the required elements (use the database tablename)
+ */
+public static function required_sample_data() {
+ return null;
+}
+```
+
+A single method must be implemented, `calculate_sample`. Most indicators make use of `$starttime` and `$endtime` to restrict the time period they consider for their calculations (for example read actions during `$starttime - $endtime` period) but some indicators may not need to apply any restriction (e.g. does this user have a user picture and profile description?) `self::MIN_VALUE` is `-1` and `self::MAX_VALUE` is `1`. We do not recommend changing these values.
+
+```php
+/**
+ * Calculates the sample.
+ *
+ * Return a value from self::MIN_VALUE to self::MAX_VALUE or null if the indicator can not be calculated for this sample.
+ *
+ * @param int $sampleid
+ * @param string $sampleorigin
+ * @param integer $starttime Limit the calculation to this timestart
+ * @param integer $endtime Limit the calculation to this timeend
+ * @return float|null
+ */
+abstract protected function calculate_sample($sampleid, $sampleorigin, $starttime, $endtime);
+```
+
+:::danger Performance
+
+Performance here is critical as it runs once for each sample and for each range in the time-splitting method; some tips:
+
+- To avoid performance issues or repeated db queries analyser classes provide information about the samples that you can use for your calculations to save some database queries. You can retrieve information about a sample with `$user = $this->retrieve('user', $sampleid)`. *retrieve()* will return false if the requested data is not available.
+- You can also overwrite *fill_per_analysable_caches* method if necessary (keep in mind though that PHP memory is not unlimited).
+- Indicator instances are reset for each analysable and time range that is processed. This helps keeping the memory usage acceptably low and prevents hard-to-trace caching bugs.
+
+:::
+
+#### Target (core_analytics\local\target\base)
+
+Targets must extend `\core_analytics\local\target\base` or its main child class `\core_analytics\local\target\binary`. Even if Moodle core includes `\core_analytics\local\target\discrete` and `\core_analytics\local\target\linear` Moodle 3.4 machine learning backends only support binary classifications. So unless you are using your own machine learning backend you need to extend `\core_analytics\local\target\binary`. Technically targets could be reused between models although it is not very recommendable and you should focus instead in having a single model with a single set of indicators that work together towards predicting accurately. The only valid use case I can think of for models in production is using different time-splitting methods for it although, again, the proper way to solve this is by using a single time-splitting method specific for your needs.
+
+The first thing a target must define is the analyser class that it will use. The analyser class is specified in `get_analyser_class`.
+
+```php
+/**
+ * Returns the analyser class that should be used along with this target.
+ *
+ * @return string The full class name as a string
+ */
+abstract public function get_analyser_class();
+```
+
+`is_valid_analysable` and `is_valid_sample` are used to discard elements that are not valid for your target.
+
+```php
+/**
+ * Allows the target to verify that the analysable is a good candidate.
+ *
+ * This method can be used as a quick way to discard invalid analysables.
+ * e.g. Imagine that your analysable don't have students and you need them.
+ *
+ * @param \core_analytics\analysable $analysable
+ * @param bool $fortraining
+ * @return true|string
+ */
+public function is_valid_analysable(\core_analytics\analysable $analysable, $fortraining = true);
+```
+
+```php
+/**
+ * Is this sample from the $analysable valid?
+ *
+ * @param int $sampleid
+ * @param \core_analytics\analysable $analysable
+ * @param bool $fortraining
+ * @return bool
+ */
+public function is_valid_sample($sampleid, \core_analytics\analysable $analysable, $fortraining = true);
+```
+
+`calculate_sample` is the method that calculates the target value.
+
+```php
+/**
+ * Calculates this target for the provided samples.
+ *
+ * In case there are no values to return or the provided sample is not applicable just return null.
+ *
+ * @param int $sampleid
+ * @param \core_analytics\analysable $analysable
+ * @param int|false $starttime Limit calculations to start time
+ * @param int|false $endtime Limit calculations to end time
+ * @return float|null
+ */
+protected function calculate_sample($sampleid, \core_analytics\analysable $analysable, $starttime = false, $endtime = false);
+```
+
+You may wish to add to the list of **actions** that will be offered to the recipient of an insight:
+
+```php
+/**
+ * Suggested actions for a user.
+ *
+ * @param \core_analytics\prediction $prediction
+ * @param bool $includedetailsaction
+ * @param bool $isinsightuser
+ * @return \core_analytics\prediction_action[]
+ */
+public function prediction_actions(\core_analytics\prediction $prediction, $includedetailsaction = false,
+ $isinsightuser = false)
+```
+
+You may override the users who will receive **insights notifications**:
+
+```php
+/**
+ * Returns the list of users that will receive insights notifications.
+ *
+ * Feel free to overwrite if you need to but keep in mind that moodle/analytics:listinsights
+ * or moodle/analytics:listowninsights capability is required to access the list of insights.
+ *
+ * @param \context $context
+ * @return array
+ */
+public function get_insights_users(\context $context)
+```
+
+You can implement a `always_update_analysis_time()` method so analysable elements' `timeanalysed` is only updated when analysable elements have been successfully evaluated. It is useful for lightweight targets.
+
+```php
+/**
+ * Update the last analysis time on analysable processed or always.
+ *
+ * If you overwrite this method to return false the last analysis time
+ * will only be recorded in DB when the element successfully analysed. You can
+ * safely return false for lightweight targets.
+ *
+ * @return bool
+ */
+public function always_update_analysis_time()
+```
+
+If you choose to implement `ignored_predicted_classes`, it must be public:
+
+```php
+
+/**
+ * Returns the predicted classes that will be ignored.
+ *
+ * @return array
+ */
+public function ignored_predicted_classes()
+```
+
+You can override the default message provided in the insight with `get_insight_subject()`:
+
+```php
+/**
+ * The insight notification subject.
+ *
+ * This is just a default message, you should overwrite it for a custom insight message.
+ *
+ * @param int $modelid
+ * @param \context $context
+ * @return string
+ */
+public function get_insight_subject(int $modelid, \context $context)
+```
+
+You can also override the URL to the insight with get_insight_context_url():
+
+```php
+/**
+ * URL to the insight.
+ *
+ * @param int $modelid
+ * @param \context $context
+ * @return \moodle_url
+ */
+public function get_insight_context_url($modelid, $context)
+```
+
+#### Analysis interval (core_analytics\local\time_splitting\base)
+
+Analysis intervals are used to define when the analytics API will train the predictions processor and when it will generate predictions. As explained above in the [Analysis intervals](./index.md#analysis-intervals) documentation, they define time ranges based on analysable elements start and end timestamps.
+
+The base class is `\core_analytics\local\time_splitting\base`; if what you are after is to split the analysable duration in equal parts or in cumulative parts you can extend `\core_analytics\local\time_splitting\equal_parts` or `\core_analytics\local\time_splitting\accumulative_parts` instead.
+
+`define_ranges` is the main method to implement and its values mostly depend on the current analysable element (available in `$this->analysable`). An array of time ranges should be returned, each of these ranges should contain 3 attributes: A start time ('start') and an end time ('end') that will be passed to indicators so they can limit the amount of activity logs they read; the 3rd attribute is 'time', which value will determine when the range will be executed.
+
+```php
+/**
+ * Define the time splitting methods ranges.
+ *
+ * 'time' value defines when predictions are executed, their values will be compared with
+ * the current time in ready_to_predict
+ *
+ * @return array('start' => time(), 'end' => time(), 'time' => time())
+ */
+protected function define_ranges();
+```
+
+A name and description should also be specified:
+
+```php
+/**
+ * Returns a lang_string object representing the name for the time splitting method.
+ *
+ * Used as column identificator.
+ *
+ * If there is a corresponding '_help' string this will be shown as well.
+ *
+ * @return \lang_string
+ */
+public static function get_name() : \lang_string;
+```
+
+
+Provides the activity task class +- **backup_foobar_stepslib.php**
+Provides all the backup steps classes + +If your module declares its own backup setting (apart from the ones common for all activity modules provided by the core), you will also want to create the backup_foobar_settingslib.php file to provide the setting classes. However most modules do not need this feature. + +### Backup task class + +The file backup_foobar_activity_task.class.php must provide a single class called **backup_foobar_activity_task**. All activity tasks extend the backup_activity_task class. + +There are three methods that your class must define. + +- **protected function define_my_settings()**
+If your module declares own backup settings defined in the file backup_foobar_settingslib.php, add them here. Most modules just leave the method body empty. +- **protected function define_my_steps()**
+This method typically consists of one or more `$this->add_step()` calls. This is the place where you define the task as a sequence of steps to execute. +- **static public function encode_content_links($content)**
+The current instance of the activity may be referenced from other places in the course by URLs like `http://my.moodle.site/mod/foobar/view.php?id=42` Obviously, such URLs are not valid any more once the course is restored elsewhere. For this reason the backup file does not store the original URLs but encodes them into a transportable form. During the restore, the reverse process is applied and the encoded URLs are replaced with the new ones valid for the target site. + +### Backup structure step class + +The classes that represent the backup steps added in define_my_steps() are implemented in the file backup_foobar_stepslib.php. Most plugins define just a single step in the class called **backup_foobar_activity_structure_step** that extends the backup_activity_structure_step class. This class defines the structure step - that is the step where the structure of your plugin's instance data is described and linked with the data sources. + +You have to implement a single method `protected function define_structure()` in this class class. There are three main things that the method must do. + +- Create a set of backup_nested_element instances that describe the required data of your plugin +- Connect these instances into a hierarchy using their `add_child()` method +- Set data sources for the elements, using their methods like `set_source_table()` or `set_source_sql()` + +The method must return the root backup_nested_element instance processed by the `prepare_activity_structure()` method (which just wraps your structures with a common envelope). + +## API for blocks + +### Files + +The files that implement the backup support in your block must be located in the subdirectory backup/moodle2/ in your plugin's folder. So, if you are developing the block called *foobar* then the backup files will be located in blocks/foobar/backup/moodle2/ folder. + +At least the file backup_foobar_block_task.class.php is supposed to exist in that location (replace *foobar* with the name of your block). + +If your block defines its own database tables, data from which must be included in the backup, you will want to create a file backup_foobar_stepslib.php, too. Additionally, if your block declares its own backup setting, you will also want to create the backup_foobar_settingslib.php file to provide the setting classes. However most blocks do not need this feature. + +### Backup task class + +The file backup_foobar_block_task.class.php must provide a single class called **backup_foobar_block_task**. All block tasks extend the backup_block_task class. + +There are five methods that your class must define. + +- **protected function define_my_settings()**
+If your block declares own backup settings defined in the file backup_foobar_settingslib.php, add them here. Most blocks just leave the method body empty. +- **protected function define_my_steps()**
+Blocks that do not have their own database tables usually leave this method empty. Otherwise this method consists of one or more `$this->add_step()` calls where you define the task as a sequence of steps to execute. +- **public function get_fileareas()**
+Returns the array of file area names within the block context. +- **public function get_configdata_encoded_attributes()**
+Instead of using their own tables, blocks usually use the configuration tables to hold their data (see the instance_config_save() of the block class). This method returns the array of all config elements that must be processed before they are stored in the backup. This is typically used when the stored config elements holds links to embedded media. Most blocks just return empty array here. +- **static public function encode_content_links($content)**
+If the current instance of the block may be referenced from other places in the course by URLs, it must be encoded into a transportable form. Most blocks just return unmodified $content parameter. + +## API for admin tools + +The files that implement the backup support in your plugin must be located in the subdirectory *backup/moodle2/* in your plugin's folder. So, if you are developing *tool_foobar* then the backup files will be located in *admin/tool/foobar/backup/moodle2/*. + +### Task class + +The file backup_tool_foobar_plugin.class.php must provide a single class called *backup_tool_foobar_task* extending *backup_tool_plugin*. + +Here is a minimalistic task: + +```php +require_once($CFG->dirroot . '/backup/moodle2/backup_tool_plugin.class.php'); + +class backup_tool_foobar_plugin extends backup_tool_plugin { + + protected function define_course_plugin_structure() { + $this->step->log('Yay, backup!', backup::LOG_DEBUG); + return $plugin; + } + +} +``` + +## API for themes + +See [Backup 2.0 theme data](https://docs.moodle.org/dev/Backup_2.0_theme_data) + +## API for reports + +See [Backup 2.0 course report data](https://docs.moodle.org/dev/Backup_2.0_course_report_data) + +## See also + +- [Restore API](./restore.md) +- [Core APIs](../../../apis.md) diff --git a/versioned_docs/version-5.1/apis/subsystems/backup/restore.md b/versioned_docs/version-5.1/apis/subsystems/backup/restore.md new file mode 100644 index 0000000000..10539c31dc --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/backup/restore.md @@ -0,0 +1,58 @@ +--- +title: Restore API +tags: + - Subsystem + - API + - Backup +--- +The Restore API provides a way to restore your plugin's data from a backup file created in Moodle 2.0 or later. For the information on how backup files are created, see [Backup API](./index.md). For the information on how to support restoring data from backup files created in Moodle 1.x, see [Backup conversion API](https://docs.moodle.org/dev/Backup_conversion_API). + +## Overview + +This page provides just a quick reference to the restore machinery in Moodle 2.0 and higher. There is a detailed documentation available at [Backup 2.0](https://docs.moodle.org/dev/Backup_2.0) page - see especially the tutorial for plugin authors at [Restore 2.0 for developers](https://docs.moodle.org/dev/Restore_2.0_for_developers) page. + +Moodle restores data from course backups by executing so called *restore plan*. The restore plan consists of a set of *restore tasks* and finally each restore task consists of one or more *restore steps*. You as the developer of a plugin will have to implement one restore task that deals with your plugin data. Most plugins have their restore tasks consisting of a single restore step - the one that parses the plugin XML file and puts the data into its tables. + +## API for activity modules + +### Files + +The files that implement the restore support in your activity module must be located in the subdirectory `backup/moodle2/` in your plugin's folder (yes, it's the same folder where the backup related files are located). So, if you are developing the activity module called *foobar* then the restore files will be located in `mod/foobar/backup/moodle2/` folder. + +The following two files are supposed to exist in that location (replace *foobar* with the name of your module): + +- **restore_foobar_activity_task.class.php**
+Provides the activity task class +- **restore_foobar_stepslib.php**
+Provides all the restore steps classes + +(to be continued) + +## API for admin tools + +The files that implement the backup support in your plugin must be located in the subdirectory `backup/moodle2/` in your plugin's folder. So, if you are developing `tool_foobar` then the backup files will be located in `admin/tool/foobar/backup/moodle2/`. + +### Task class + +The file `backup_tool_foobar_plugin.class.php` must provide a single class called `restore_tool_foobar_task` extending `restore_tool_plugin`. + +Here is a minimalistic task: + +```php +require_once($CFG->dirroot . '/backup/moodle2/restore_tool_plugin.class.php'); + +class restore_tool_foobar_plugin extends restore_tool_plugin { + + protected function define_course_plugin_structure() { + $paths = array(); + $this->step->log('Yay, restore!', backup::LOG_DEBUG); + return $paths; + } + +} +``` + +## See also + +- [Core APIs](../../../apis.md) +- [Backup API](../backup) diff --git a/versioned_docs/version-5.1/apis/subsystems/check/index.md b/versioned_docs/version-5.1/apis/subsystems/check/index.md new file mode 100644 index 0000000000..4e6866851a --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/check/index.md @@ -0,0 +1,247 @@ +--- +title: Check API +tags: + - API +--- + +A _Check_ is a runtime test to make sure that something is working well. You can think of Checks as similar and complimentary to the [PHPUnit](/general/development/tools/phpunit) and [Acceptance testing](/general/development/tools/behat) but the next layer around them, and performed at run time rather than development, or build time. + +Like other forms of testing the tests themselves should be easy to read, to reason about, and to confirm as valid. + +:::note + +Many types of runtime checks cannot be unit tested, and often the checks **are** the test. + +::: + +Checks can be used for a variety of purposes including: + +- configuration checks +- security checks +- status checks +- performance checks +- health checks + +Moodle has had various types of checks and reports for a long time but they were inconsistent and not machine readable. In Moodle 3.9 they were unified under a single Check API which also enabled plugins to cleanly define their own additional checks. Some examples include: + +- a password policy plugin could add a security check +- a custom authentication plugin can add a check that the upstream identity system can be connected to +- a MUC store plugin could add a performance check +Having these centralized and with a consistent contract makes it much easier to ensure the whole system is running smoothly. This makes it possible for an external integration with monitoring systems such as Nagios / Icinga. The Check API is exposed as an NPRE compliance cli script: + +```console +php admin/cli/checks.php +``` + +## Result states of a check + +| Status | Meaning | Example | +| --- | --- | --- | +| N/A | This check doesn't apply - but we may still want to expose the check | secure cookies setting is disabled because site is not https | +| Ok | A component is configured, working and fast. | ldap can bind and return value with low latency | +| Info | A component is OK, and we may want to alert the admin to something non urgent such as a deprecation, or something which needs to be checked manually. | | +| Unknown | We don't yet know the state. eg it may be very expensive so it is run using the Task API and we are waiting for the answer. NOTE: unknown is generally a bad thing and is semantically treated as an error. It is better to have a result of Unknown until the first result happens, and from then on it is Ok, or perhaps Warning or Error if the last known result is getting stale. If you are caching or showing a stale result you should expose the time of this in the result summary text. | A complex user security report is still running for the first time. | +| Warning | Something is not ideal and should be addressed, eg usability or the speed of the site may be affected, but it may self heal (eg a load spike) | auth_ldap could bind but was slower than normal | +| Error | Something is wrong with a component and a feature is not working | auth_ldap could not connect, so users cannot start new sessions | +| Critical | An error which is affecting everyone in a major way | Cannot read site data or the database, the whole site is down | + +How the various states are then leveraged is a local decision. A typical policy might be that health checks with a status of 'Error' or 'Critical' will page a system administrator 24/7, while 'Warning' only pages during business hours. + +## Check types and reports + +Checks are broken down into types, which roughly map to a step in the life cycle of your Moodle System. + +### Environmental checks + +Available from _/admin/environment.php_, environmental checks make sure that a Moodle instance is fully configured. + +This page is a potential candidate to move to the new Check API but it slightly more complex than the other checks so it hasn't been tackled yet. It would be a deeper change and this is intrinsically part of the install and upgrade system. It is not as critical to refactor as it is already possible for a plugin to declare its own checks, via either declarative [Environment checking](https://docs.moodle.org/dev/Environment_checking) or programmatically with a custom check: + +### Configuration checks + +Available from _/admin/index.php?cache=1_, the Admin notifications page performs a mixture of checks, including security, status, and performance checks. + +None of these checks are as exhaustive as the checks in the reports below. It also does additional checks including whether the web services for the Moodle Mobile App are enabled, and whether the site has been registered. + +### Security checks (security) + +Available from _/report/security/index.php_, these checks make sure that a Moodle instance is hardened correctly for your needs. + +For more information see [MDL-67776](https://moodle.atlassian.net/browse/MDL-67776). + +### Status checks (status) + +Available from _/report/status/index.php_, a status check is an 'in the moment' test and covers operational tests such as 'can moodle connect to ldap'. The main core status checks are that cron is running regularly and there has been no failed tasks. + +:::danger Important + +It is critical to understand that Status checks are conceptually defined at the level of the application and not at a lower host level such as a docker container or node in a cluster. Checks should be defined so that whichever instance you ask you should get a consistent answer. DO NOT use the Status Checks to detect containers which need to be reaped or restarted. If you do, any status errors may mean all containers will simultaneously be marked for reaping. + +An additional status check is likely the most common type of check a plugin would define. Especially a plugin that connects to a 3rd party service. If the concept of 'OK' requires some sort of threshold, eg network response within 500ms, then that threshold should be managed by the plugin and optionally exposed as a admin setting. The plugin may choose to have different thresholds for Warning / Error / Critical. When designing a new Status Check be mindful that it needs to be actionable, for instance if you are asserting that a remote domain is available and it goes down, which then alerts your infrastructure team, there isn't much they can do about it if it isn't their domain. If it is borderline then make things like this configurable so that each site has to option of tune their own policies of what should be considered an issue or not. + +::: + +For more information see [MDL-47271](https://moodle.atlassian.net/browse/MDL-47271). + +### Performance checks (performance) + +Available from _/report/performance/index.php_, each check might simply check for certain settings which are known to slow things down, or it might actually do some sort of test like multiple reads and writes to the db or filesystem to get a performance metric. + +## Implementing a new check + +### A check class + +And make a new check class in `mod/myplugin/classes/check/foobar.php` and the only mandatory method is `get_result()`. By default it will use a set language string but you can override the `get_name()` method to reuse an existing string. + +```php title="mod/myplugin/lang/en/myplugin.php" +$string['checkfoobar'] = 'Check the foos to make sure they are barred'; +``` + +```php title="mod/myplugin/classes/check/foobar" +id = "foobar{$id}"; + } + + public function get_id(): string { + return $this->id; + } + ... +} +``` + +### Make checks as fast as practical + +As many checks will be run and compiled into a report we want the checks themselves to be simple and as fast as possible. For instance an auth_ldap check while authenticating an end user could have a timeout of 60 seconds, and the check could warn if it takes more than 2 seconds. But the check could have a hard timeout of say 5 seconds and have a result status of ERROR for 5 or more seconds. + +### Lazy loading expensive result details + +Checks can provide details on a check, such as the complete list of bad records. Generally this type of information might be expensive to produce so you can defer this lookup until get_details() is called specifically rather than setting this in the constructor. It will only be loaded on demand and shown when you drill down into the check details page. + +```php +add(new admin_setting_check( + 'antivirus/checkantivirus', + new \core\check\environment\antivirus(), +)); +``` + +:::info + +These checks are performed asynchronously, and only if the check is visible, so will not slow down the whole admin tree which is often a downside of implementing this manually. + +::: + +You can also use checks which are not linked into one of the reports. This means you can check the connection while configuring the plugin, but before it is enabled, and only add the check to the status report page once the plugin is enabled. + +## See also + +- [Performance overview](https://docs.moodle.org/en/Performance_overview) user docs diff --git a/versioned_docs/version-5.1/apis/subsystems/communication/index.md b/versioned_docs/version-5.1/apis/subsystems/communication/index.md new file mode 100644 index 0000000000..de1de2579f --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/communication/index.md @@ -0,0 +1,318 @@ +--- +title: Communication API +tags: + - communication + - provider + - Communication provider + - Communication room + - Communication service + - Chat +documentationDraft: true +--- + +Communication API provides access to the messaging system and other communication providers (such as Matrix). +This API the management of room and members to that room. + +Communication API actions its tasks happens asynchronously using ad-hoc tasks. This means that the API functions will return immediately and the action will be +executed in the background. Communication API has multiple interfaces which acts like a feature of the API. Each of these interface/features have one or more associated +ad-hoc tasks. These tasks are responsible to action the requested feature from the provider plugin (such as Matrix) informed by the Communication API instance. For developers +to interact with the API, they must use the public API (`communication\api`). + +Communication API allows to add ad-hoc tasks to the queue to perform actions on the communication providers. This API will not allow any immediate actions to be performed on the +communication providers. It will only add the tasks to the queue. The exception has been made for deletion of members in case of deleting the user. This is because the user will +not be available for any checks (capability, role etc.) after deleted. + +:::info + +This is an experimental feature. To use this feature, you must enable the experimental feature flag for Communication in the site administration. +Please follow the steps to enable the feature. + +1. Navigate to `Site administration > Development > Experimental` settings. +2. Tick the checkbox to enable the following feature: Enable communication providers (`enablecommunicationsubsystem`). + +::: + +## Hooks + +The Communication API takes advantage of the [Hooks API](../../plugintypes/communication/index.md) with actions performed in the following way: + +1. Actions in core have their own hook dispatched (for example enrol, change role, add to group). +2. Hooks are then registered to a particular callback (`lib/db/hooks.php`). +3. Callbacks are then listened for inside the Communication API's hook listener (`communication\hook_listener`) where all the logic is performed. +4. To identify the ones Communication API is using, the callbacks will be methods from Communication API's hook listener (`communication\hook_listener`). + +## Important features of the API + +The below are the important methods/features of the API. These methods/features are the ones which can be used to interact with the communication API. + +### Loading a communication instance + +To load a communication instance, you must use the `communication\api::load_by_instance()` method. This method will return a communication instance which can be +used to interact with the communication API and its related methods. The below example shows how to load a communication instance for a course, where the +context is the actual course context object, component is the component name (`core_course`), instance type is the custom string which can change according to +the usage and instance id is the course id. The constructor of the public api is private and hence the only way to load an instance is through +the `load_by_instance()` method. The provider is the name of the provider plugin which is used to load the instance. It's optional, if not provided, it will load +the enabled provider for that instance. + +```php +$communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $courseid, + provider: 'communication_matrix', +); +``` + +### Create and configure a room + +`$communication->create_and_configure_room()` method is used to add an ad-hoc to create a room in the communication provider and configure it with the required settings. + +```php +public function create_and_configure_room( + string $communicationroomname, + ?\stored_file $avatar = null, + ?\stdClass $instance = null, +); +``` + +This method takes the following parameters: + +- The name of the room as a string to be created. +- The avatar of the room to be created, this is a stored file object. +- The instance object of the communication API. + +For example, we want to create a room for a course with the course name as the room name and the course image as the avatar, we can use the below code. +There can be other cases where information from course instance will be used by a plugin, for example, the dynamic field from matrix plugin has a form +field named topic which sets the topic of the room, the instance object can be used to get the topic from the course instance and set it in the form field. +Please refer to [Communication plugin](../../plugintypes/communication/index.md) documentation for more details. + +```php +// First initialize the communication instance, +// provided the context is already initialized +// and the selected provider is available +// though a form or other means. +$communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $course->id, + provider: 'communication_matrix', +); + +// Now call the create_and_configure_room() method +// to add an ad-hoc to create a room in the +// communication provider and configure it with the +// required settings. +$communication->create_and_configure_room( + communicationroomname: $course->fullname, + avatar: $courseimage ?: null, + instance: $course, +); +``` + +### Update a room and its associated information + +`$communication->update_room()` method is used to add an ad-hoc to update a room in the communication provider and configure it with the required settings. + +```php +public function update_room( + ?int $active = null, + ?string $communicationroomname = null, + ?\stored_file $avatar = null, + ?\stdClass $instance = null, +); +``` + +This method takes the following parameters: + +- The active status of the room to be updated. Can be either 0 or 1. +- The name of the room as a string to be updated. +- The avatar of the room to be updated, this is a stored file object. +- The instance object of the communication API. + +```php +// First initialize the instance. +$communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $course->id, + provider: 'communication_matrix', +); + +// Now update the room with the required settings. +// The instance will be used by dynamic fields feature of the plugin +// to allow the plugin to get the required information from the instance. +$communication->update_room( + active: $active, + communicationroomname: $communicationroomname, + avatar: $courseimage ?: null, + instance: $course, +); +``` + +### Delete a room + +`$communication->delete_room()` method is used to add an ad-hoc to delete a room in the communication provider. The associated task for this also removes all the members from +the room before deleting the room. + +:::danger + +This is destructive and might remove all the messages and other data associated with the room. Usage of this should be done with caution. + +::: + +### Create and configure a room according to the provider + +There are cases where the provider is changed for a communication instance. +For example, previously the provider was set to _Provider B_ and now it has changed to _Provider A_. +In this case, the room and its members need to be configured according to the new provider. Without any extra logic needed, the method `$communication->configure_room_and_membership_by_provider()` takes care of this in the following way: + +1. Communication provider is changed from _Provider B_ to _Provider A_. +2. New room is created in _Provider A_. +3. Members are added to the new room at _Provider A_. +4. Members are removed from the old room at _Provider B_. + +```php +// First initialize the instance. +$communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $course->id, + provider: 'communication_matrix', + ); + +// Now call this with the new provider to take care of the room and its members for the new provider. +$communication->configure_room_and_membership_by_provider( + provider: 'communication_slack', + instance: $course, + communicationroomname: $coursecommunicationroomname, + users: $enrolledusers, + instanceimage: $courseimage, + ); +``` + +### Add members to a room + +`$communication->add_members_to_room()` method is used to add an ad-hoc to add members to a room in the communication provider. The user id of each user to be added to +the provider room is also stored in the communication_user table for user mapping with the provider. + +```php +public function add_members_to_room( + array $userids, + bool $queue = true, +); +``` + +This method accepts the following parameters: + +- An array of user ids to be added to the provider room. +- A boolean value to indicate if the task should be added to the queue or run immediately. This is false by default. This is added to ensure the cases where the mapping should be created but the task might not be needed at this point. + +```php +// First initialize the instance, provider is not required here, it will initialize the enabled instance. +$communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $course->id, +); + +// Now add the members. +$communication->add_members_to_room( + userids: $enrolledusers, +); +``` + +### Update the membership of a room + +`$communication->update_room_membership()` method is used to add an ad-hoc to update the membership of a room in the communication provider. +The user mapping for each of the users are also reset to allow task to update the users from the task. + +```php +public function update_room_membership( + array $userids, + bool $queue = true, +); +``` + +This method accepts the same parameters as the `add_members_to_room()` method and the usage is also the same. + +### Remove members from a room + +`$communication->remove_members_from_room()` method is used to add an ad-hoc to remove members from a room in the communication provider. +The users are flagged as deleted in the communication_user table to allow the task to remove the users from the provider room. + +```php +public function remove_members_from_room( + array $userids, + bool $queue = true +); +``` + +This method accepts the same parameters as the `add_members_to_room()` method and the usage is also the same. + +It's also possible to remove all members from a room by using `$communication->remove_all_members_from_room()`. This method does not take any parameters and will remove all users from the room and delete the user mapping found in the `communication_user` table. + +:::caution + +Both `$communication->remove_all_members_from_room()` and `$communication->remove_members_from_room()` will remove users and may delete communication history from the provider itself. + +::: + +### Show the communication room creation status notification + +`$communication->show_communication_room_status_notification()` is a special method to have a UI element to show the status of the room creation. If the room is ready, it will +return the notification as a string. If the room is not ready, it will return pending status. Course have this implemented and shows the status after the communication instance +is configured. Please note, the status notification relies on the creation of room, not the memberships of the room. + +### Communication instance setup using form/configuration page + +The communication API allows to have settings to configure the basic information like room name, selection of provider etc. `$communication->form_definition()` method +is used to get the form definition for the settings form. If the form elements are used in another form to include the communication form elements, `form_definition()` method +will be useful. There is a configuration page (`communication/configure.php`) which can be used to configure the communication instance. Course currently uses this page to set up +communication and its associated information. +It will also be required to use `set_data()` method in order to set the data to the form elements while saving the data. + +```php +public function form_definition( + \MoodleQuickForm $mform, + string $selectdefaultcommunication = processor::PROVIDER_NONE, +); +``` + +This method accepts the following parameters: + +- The moodle quick form object to add the form elements to. +- The default provider to be selected in the form. This is set to none by default. + +For example, we have a form where we want to have the communication settings, we can use the below code to add the form elements to the form. + +```php +class configure_form extends \moodleform { + public function definition() { + $mform = $this->_form; + $communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $course->id, + ); + $communication->form_definition(mform: $mform); + $this->communication->set_data(instance: $course); + } +} +``` + +## Building a communication plugin + +Communication API also provides a bunch of interfaces for a communication plugin to consume. Every plugin should implement these interfaces according to the features they +support. + +:::info + +Please refer to [Communication plugin](../../plugintypes/communication/index.md) documentation for more details about building a plugin. + +::: diff --git a/versioned_docs/version-5.1/apis/subsystems/editor/index.md b/versioned_docs/version-5.1/apis/subsystems/editor/index.md new file mode 100644 index 0000000000..bdb2afb1f1 --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/editor/index.md @@ -0,0 +1,54 @@ +--- +title: Editor API +tags: [] +documentationDraft: true +--- + +The editor API lets you control Moodle text editors. It can be found in `lib/editorlib.php`. + +:::important + +Normally you do not need to use this API directly because you can include editors as part of a Moodle form, which will automatically set up the editor for you. + +::: + +## How to set up a text editor + +To set up a text editor on an existing HTML text area field: + +- Call function `editors_get_preferred_editor()`, which will return an object of the texteditor class. +- Call function `use_editor()` to enable the editor for the text area. + +For example, assuming there is an HTML text area with id `mytextareaid`: + +```php +$editor = editors_get_preferred_editor(FORMAT_HTML); +$editor->use_editor('mytextareaid'); +``` + +## Editor options + +The use_editor function allows an options array to be supplied. + +### General options + +- `context`: set to the current context object +- `enable_filemanagement`: set false to disable the file management plugin +- `autosave`: set false to disable autosave + +### Atto-specific options + +- `toolbar`: set to override which icons appear on the toolbar (normally it uses the admin setting - this is for special cases for example if you want a minimal editor in a particular plugin). + +The following example will cause atto to show the four buttons indicated. + +```php +$attobuttons = 'style1 = bold, italic' . PHP_EOL . 'list = unorderedlist, orderedlist'; +$editor->use_editor($id, [ + 'context' => $context, + 'autosave' => false, + 'atto:toolbar' => $attobuttons +], [ + 'return_types' => FILE_EXTERNAL, +]); +``` diff --git a/versioned_docs/version-5.1/apis/subsystems/enrol.md b/versioned_docs/version-5.1/apis/subsystems/enrol.md new file mode 100644 index 0000000000..c1044c66a8 --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/enrol.md @@ -0,0 +1,258 @@ +--- +title: Enrolment API +tags: + - Enrolment + - Library +--- + + + +The enrolment API gives access to the enrolment methods and also to [enrolment plugins](../plugintypes/enrol/index.md) instances. + +## Difference between user enrolment and role assignment + +Users enrolled in a course have at least one record in `user_enrolments` table. This table has the relation between courses and users **through an enrolment plugin instance**. However, `user_enrolments` does not contain information about the user role in the course, only information about: + +- **Enrolment plugin instance** +- **Enrolment status** (active or suspended). +- **Enrolment Start and end dates**. + +The specific role assignments are related to the context, not only to course (as activities and other pages can use its own). The specific roles of a user are stored in the `role_assignments` table. This table stores: + +- The **user role id** in the **context** +- The **component item** that assigned the role. In the case of a regular course, the *component* is the name of the enrolment plugin and the *item id* is the specific plugin instance. + +### What is enrolment? + +Enrolled users may fully participate in a course. Active user enrolment allows user to enter course. Only enrolled users may be group members. Grades are stored only for enrolled users. + +### Unenrolment + +Unenrolment is irreversible operation that purges user participation information. Full unenrolment is suitable only if you do not need to preserve all course participation information including user grades. + +### Enrolment status + +Instead of full unenrolment it is usually better to only *suspend* user enrolment. If there are other ways to enter the course (such guest access) it is recommended to remove user roles at the same time. + +Enrolments have two states defined by two constants: + +- `ENROL_USER_ACTIVE` the enrolment is active +- `ENROL_USER_SUSPENDED` the enrolment is suspended + +### Activity participation + +Activity developers decide the enrolment related behaviour of module. + +There are some general guidelines: + +- Only users with active enrolments should receive notifications. +- Activities should display enrolled users with some capability as participants. +- By default only users with active enrolments should be displayed in reports. +- There should be option to display all enrolled users including suspended enrolments. +- For performance reasons invisible participation data should be purged on unenrolment. +- Contributions visible by other participants should be kept after unenrolment (such as forum posts). + +## API functions + +### is_enrolled() + +Use this method to determine if a user is enrolled into a course. This method returns true for students and teachers, but false for administrators and other managers. + +:::caution + +User enrolments can be either active or suspended, suspended users can not enter the course (unless there is some kind of guest access allowed or have `moodle/course:view` capability) and are usually hidden in the UI. + +::: + +```php +function is_enrolled( + context $context, + stdClass $user = null, + string $withcapability = '', + bool $onlyactive = false +) +``` + +Good example is choice module where we have one slot for each participant, people that are not enrolled are not allowed to vote `is_enrolled($context, $USER, 'mod/choice:choose')`. Another example is assignment where users need to be enrolled and have capability to submit assignments `is_enrolled($this->context, $USER, 'mod/assignment:submit')`. + +### get_enrolled_users() + +Returns the list of enrolled users. This method allows to filter the result by capability, pagination or state. + +```php +function get_enrolled_users( + context $context, + string $withcapability = '', + int $groupid = 0, + string $userfields = 'u.*', + ?string $orderby = null, + int $limitfrom = 0, + int $limitnum = 0, + bool $onlyactive = false +) +``` + +
Username and Password + Login Endpoint ->> Client: Session token + Client ->> Protocol Server: Function and authentication token + Protocol Server -->> External API: Access Control Check + Note right of Protocol Server: The Session token is
used to confirm
user permission against
the specified API. + External API -->> Protocol Server: Authentication granted + Protocol Server ->> Plugin API: Function called against
relevant API + Plugin API ->> Protocol Server: Result passed back to Protocol server + Protocol Server -->> External API: Return value validated + Protocol Server ->> Client: Validated data returned to Client +``` + +## Developer documentation + +The External Service API has two categories of documentation: + +1. this documentation details how to _write_ a web service and use the External API; and +2. API documentation for a live Moodle site, which can be found under ** Site administration > Server > Web services > API Documentation **. + +In addition to the standard API endpoints, several additional API endpoints are available for the purpose of uploading, and downloading, files. For more information on these endpoints, see the [file handling](./files.md) documentation. + +- [How to contribute a web service function to core](https://docs.moodle.org/dev/How_to_contribute_a_web_service_function_to_core) +- [Adding a web service to your plugin](./writing-a-service.md) +- Code example: [Adding a web service, using APIs](https://gist.github.com/timhunt/51987ad386faca61fe013904c242e9b4) by (Tim Hunt) +- [Implement a web service client](https://docs.moodle.org/dev/Creating_a_web_service_client) +- [Web services files handling](./files.md) +- [Web service Listing & Roadmap](https://docs.moodle.org/dev/Web_services_Roadmap) + +## Specification and brainstorming + +- [External services security](./security.md) +- [External services description](./description.md) + +## See also + +- [Web service API functions](https://docs.moodle.org/dev/Web_service_API_functions) +- [Web services FAQ](https://docs.moodle.org/en/Web_services_FAQ) +- [How to create and enable a web service](https://docs.moodle.org/en/How_to_create_and_enable_a_web_service) +- [How to enable the mobile web service](https://docs.moodle.org/en/Enable_mobile_web_services) +- [Web services user documentation](https://docs.moodle.org/en/Web_services) +- [Mastering Moodle Web Services development](http://www.slideshare.net/juanleyva/mastering-moodle-web-services-development) - Last session of the Hackfest in the MoodleMoot UK 2016 diff --git a/versioned_docs/version-5.1/apis/subsystems/external/security.md b/versioned_docs/version-5.1/apis/subsystems/external/security.md new file mode 100644 index 0000000000..84c00c356d --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/external/security.md @@ -0,0 +1,85 @@ +--- +title: Security +tags: + - Web Services + - core_external + - external + - API +sidebar_position: 3 +--- + +Before operating on any data in an external function, you must ensure that the user: + +- has access to context that the data is located in +- has permission to perform the relevant action + +## Validating function parameters + +Before working with any data provided by a user you **must** validate the parameters against the definitions you have defined. + +To do so you should call the `validate_parameters()` function, passing in the reference to your `execute_parameters()` function, and the complete list of parameters for the function. The function will return the validated and cleaned parameters. + +The `validate_parameters()` function is defined on the `\core_external\external_api` class, and can be called as follows: + +```php title="local/groupmanager/classes/external/create_groups.php" +public static function execute(array $groups): array { + [ + 'groups' => $groups, + ] = self::validate_parameters(self::execute_parameters(), [ + 'groups' => $groups, + ]); + // ... +} +``` + +## Validating access to the Moodle context + +Whenever fetching or updating any data within Moodle using an External function definition, you **must** validate the context that the data exists within. + +To do so you should call the `validate_context()` function, passing the _most specific_ context for the data. + +For example, if you are working with data belonging to a specific activity, you should use the _activity_ context. If you are working with data belonging to a course, you should use the _course_ context. + +If your function operates on multiple contexts (like a list of courses), you must validate each context right before generating any response data related to that context. + +The `validate_context()` function is defined on the `\core_external\external_api` class, and can be called as follows: + +```php title="local/groupmanager/classes/external/create_groups.php" +public static function execute(array $groups): array { + // ... + foreach ($groups as $group) { + $coursecontext = \context_course::instance($group['courseid']); + self::validate_context($coursecontext); + // ... + } +} +``` + +:::tip + +The `validate_context()` function will also configure the correct theme, language, and filters required to render content for the current user. + +::: + +:::caution + +You should not: + +- use the `require_login` function from an external function - this function is reserved for php scripts returning a web page. +- call `$PAGE->set_context()` manually - this will generate warning notices. + +The `validate_context()` function is the only correct way to write external functions. + +::: + +## Ensuring that a user has the appropriate rights + +Once you have confirmed that the provided data is of the correct type, and configured Moodle for the specific context, you should also ensure that all capabilities are checked correctly. + +You can use the standard capability functions, including: + +- `has_capability()` - to check that a user has a single capability +- `has_any_capability()` - to check that a user has any capability in a set +- `has_all_capability()` - to check that a user has all capabilities in a set +- `require_capability()` - to require a single capability +- `require_all_capabilities()` - to require that a user has all capabilities in a set diff --git a/versioned_docs/version-5.1/apis/subsystems/external/testing.md b/versioned_docs/version-5.1/apis/subsystems/external/testing.md new file mode 100644 index 0000000000..02390fbc7c --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/external/testing.md @@ -0,0 +1,126 @@ +--- +title: Unit Testing +tags: + - Unit testing + - Web Services + - external + - core_external + - API +--- + +Unit tests are the best way of checking the behaviour of your external services and can help you to: + +- discover use cases you didn't think about +- understand the feelings and the needs of the web service client developer +- end up with a function usable by everybody, not only by your own client +- reach integration way faster as you joined a proof of validity +- make the QA process a breeze + +Writing unit tests for an external service function is no different to writing unit tests for any other part of Moodle, which is documented in under [PHPUnit](/general/development/tools/phpunit). + +## How to write an external function PHPUnit test + +You should create one unit test testcase for each external service file, and it should be named after the file that it tests. + +For example, if you have written a service function in `[componentfolder]/classes/external/get_fruit.php`, you should write a unit test in `[componentfolder]/tests/external/get_fruit_test.php`. + +```php title="mod/kitchen/tests/external/get_fruit_test.php" +. + +/** + * Unit tests for the get_fruit function of the kitchen. + * + * @package mod_kitchen + * @category external + * @copyright 20XX Your Name + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +namespace mod_kitchen\external; + +defined('MOODLE_INTERNAL') || die(); + +global $CFG; +require_once($CFG->dirroot . '/webservice/tests/helpers.php'); + +class get_fruit_test extends externallib_advanced_testcase { + + /** + * Test the execute function when capabilities are present. + * + * @covers \mod_fruit\external\get_fruit::execute + */ + public function test_capabilities(): void { + $this->resetAfterTest(true); + + $course = $this->getDataGenerator()->create_course(); + $cm = $this->getDataGenerator()->create_module('mod_kitchen', [ + 'course' => $course->id, + ]); + + // Set the required capabilities by the external function + $contextid = context_module::instance($cm->cmid)->id; + $roleid = $this->assignUserCapability('moodle/CAPABILITYNAME', $contextid); + + // Call the external service function. + $returnvalue = get_fruit::execute([ + 'course' => $course->id, + 'cmid' => $cm->id, + ]); + + // We need to execute the return values cleaning process to simulate + // the web service server. + $returnvalue = \core_external\external_api::clean_returnvalue( + get_fruit::execute_returns(), + $returnvalue + ); + + // Assert that there was a response. + // The actual response is tested in other tests. + $this->assertNotNull($returnvalue); + } + + /** + * Test the execute function when capabilities are missing. + * + * @covers \mod_fruit\external\get_fruit::execute + */ + public function test_capabilities_missing(): void { + global $USER; + + $this->resetAfterTest(true); + + $course = $this->getDataGenerator()->create_course(); + $cm = $this->getDataGenerator()->create_module('mod_kitchen', [ + 'course' => $course->id, + ]); + + // Set the required capabilities by the external function + $contextid = context_module::instance($cm->cmid)->id; + $this->unassignUserCapability('moodle/CAPABILITYNAME', $contextid, $roleid); + + $params = [PARAM1, PARAM2, ...]; + + // Call without required capability + $this->expectException(required_capability_exception::class); + get_fruit::execute([ + 'course' => $course->id, + 'cmid' => $cm->id, + ]); + } +} +``` diff --git a/versioned_docs/version-5.1/apis/subsystems/external/writing-a-service.md b/versioned_docs/version-5.1/apis/subsystems/external/writing-a-service.md new file mode 100644 index 0000000000..83c261a82d --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/external/writing-a-service.md @@ -0,0 +1,488 @@ +--- +title: Writing a new service +tags: + - Web Services + - Plugins + - core_external + - external +sidebar_position: 5 +--- + +This documentation covers the creation of a new external service for use in a web service of a fictional local plugin, `local_groupmanager`. + +## Functional specification + +The `local_groupmanager` plugin has a need to create groups within a course and would like to do so using its own web service. + +:::important + +When defining a new service definition, Moodle requires that the name of the definition be in the form: + +```sh +[frankenstyle_component]_[methodname] +``` + +The [naming convention](https://moodledev.io/general/development/policies/naming#web-services) further dictates that the `methodname` component be in the form: + +```sh +[methodname] - The name of the method in the form of [verb]_[noun] +[verb] - Usually one of get, create, delete, update + A similar verb that well describes the action may also be used +[noun] - The object being modified + Usually in Plural form +``` + +::: + +Per the Moodle naming convention for web services the name of the function should be: + +``` +local_groupmanager_create_groups +``` + +### Inputs + +The `local_groupmanager_create_groups` external service definition will take a list of _groups_ as its only parameters. + +### Outputs + +The service will return a list of the created groups, including the `id` element of those groups. + +### Exceptions and failures + +If _any_ group creation fails, the function will throw an exception, and no groups will be created. + +## Technical specification + +- **the core function the external function will call**: `groups_create_group()` from [/group/lib.php](http://github.com/moodle/moodle/tree/main/moodle/group/lib.php). +- **the parameter types**: a list of object. This object are groups, with `id`/`name`/`courseid`. +- **the returned value types**: a list of objects (groups) with their id. +- **the user capabilities to check**: `moodle/course:managegroups` + +## Declare the web service function + +An external function must be declared before it can be used in your plugin. +Function declarations should be placed in the `db/services.php` file of your plugin. For example in our fictitious plugin this would be located in `local/groupmanager/db/services.php`. + +```php +$functions = [ + // The name of your web service function, as discussed above. + 'local_groupmanager_create_groups' => [ + // The name of the namespaced class that the function is located in. + 'classname' => 'local_groupmanager\external\create_groups', + + // A brief, human-readable, description of the web service function. + 'description' => 'Creates new groups.', + + // Options include read, and write. + 'type' => 'write', + + // Whether the service is available for use in AJAX calls from the web. + 'ajax' => true, + + // An optional list of services where the function will be included. + 'services' => [ + // A standard Moodle install includes one default service: + // - MOODLE_OFFICIAL_MOBILE_SERVICE. + // Specifying this service means that your function will be available for + // use in the Moodle Mobile App. + MOODLE_OFFICIAL_MOBILE_SERVICE, + ] + ], +]; +``` + +
+
+```php
+public static function get_biscuit_parameters() {
+ return new external_function_parameters([
+ 'chocolatechips' => new external_value(
+ PARAM_BOOL,
+ 'if biscuit contains chocolate chips',
+ VALUE_REQUIRED
+ ),
+ 'glutenfree' => new external_value(
+ type: PARAM_BOOL,
+ required: VALUE_DEFAULT,
+ default: false,
+ allownull: false
+ ),
+ // ERROR! top level optional parameter!!!
+ 'icingsugar' => new external_value(
+ PARAM_BOOL,
+ 'if biscuit has icing sugar on top',
+ VALUE_OPTIONAL
+ ),
+ ]);
+}
+```
+
+
+
+
+
+```php
+public static function get_biscuit_parameters() {
+ return new external_function_parameters([
+ 'ifeellike' => new external_single_structure([
+ 'chocolatechips' => new external_value(
+ PARAM_BOOL,
+ 'if biscuit contains chocolate chips',
+ VALUE_REQUIRED
+ ),
+ 'glutenfree' => new external_value(
+ type: PARAM_BOOL,
+ required: VALUE_DEFAULT,
+ default: false,
+ allownull: false
+ ),
+ // ALL GOOD!! We have nested the params in an external_single_structure.
+ 'icingsugar' => new external_value(
+ PARAM_BOOL,
+ 'if biscuit has icing sugar on top',
+ VALUE_OPTIONAL
+ ),
+ ]),
+ ]);
+}
+```
+
+
+
+:::
+
+## Implement the external function
+
+We declared our web service function and we defined the external function parameters and return values. We will now implement the external function:
+
+```php
+ /**
+ * Create groups
+ * @param array $groups array of group description arrays (with keys groupname and courseid)
+ * @return array of newly created groups
+ */
+ public static function execute($groups) {
+ global $CFG, $DB;
+ require_once("$CFG->dirroot/group/lib.php");
+
+ $params = self::validate_parameters(self::execute_parameters(), ['groups' => $groups]);
+
+ $transaction = $DB->start_delegated_transaction(); //If an exception is thrown in the below code, all DB queries in this code will be rollback.
+
+ $groups = array();
+
+ foreach ($params['groups'] as $group) {
+ $group = (object)$group;
+
+ if (trim($group->name) == '') {
+ throw new invalid_parameter_exception('Invalid group name');
+ }
+ if ($DB->get_record('groups', ['courseid' => $group->courseid, 'name' => $group->name])) {
+ throw new invalid_parameter_exception('Group with the same name already exists in the course');
+ }
+
+ // now security checks
+ $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
+ self::validate_context($context);
+ require_capability('moodle/course:managegroups', $context);
+
+ // finally create the group
+ $group->id = groups_create_group($group, false);
+ $groups[] = (array) $group;
+ }
+
+ $transaction->allow_commit();
+
+ return $groups;
+ }
+```
+
+### Parameter validation
+
+```php
+$params = self::validate_parameters(self::execute_parameters(), [
+ 'groups' => $groups,
+]);
+```
+
+This *validate_parameters* function validates the external function parameters against the description. It will return an exception if some required parameters are missing, if parameters are not well-formed, and check the parameters validity. It is essential that you do this call to avoid potential hack.
+
+**Important:** the parameters of the external function and their declaration in the description **must be the same order**. In this example we have only one parameter named $groups, so we don't need to worry about the order.
+
+### Context and Capability checks
+
+```php
+// Perform security checks.
+$context = context_course::instance($group->courseid);
+self::validate_context($context);
+require_capability('moodle/course:managegroups', $context);
+```
+
+Note: validate_context() is required in all external functions before operating on any data belonging to a context. This function does sanity and security checks on the context that was passed to the external function - and sets up the global $PAGE and $OUTPUT for rendering return values. Do NOT use require_login(), or $PAGE->set_context() in an external function.
+
+### Exceptions
+
+You can throw exceptions. These are automatically handled by Moodle web service servers.
+
+```php
+// Note: It is good practice to add detailled information in $debuginfo,
+// and only send back a generic exception message when Moodle DEBUG mode < NORMAL.
+// It's what we do here throwing the invalid_parameter_exception($debug) exception
+throw new invalid_parameter_exception('Group with the same name already exists in the course');
+```
+
+### Correct return values
+
+The return values will be validated by the Moodle web service servers:
+
+- return values contain some values not described => these values will be skipped.
+- return values miss some required values (VALUE_REQUIRED) => the server will return an error.
+- return values types don't match the description (int != PARAM_ALPHA) => the server will return an error
+**Note:** cast all your returned objects into arrays.
+
+## Bump the plugin version
+
+Edit your `local/groupmanager/version.php` and increase the plugin version. This should trigger a Moodle upgrade and the new web service should be available in the administration (*Administration > Plugins > Web Services > Manage services*)
+
+## Deprecation
+
+External functions deprecation process is slightly different from the standard deprecation. If you are interested in deprecating any of your external functions you should **also** (apart from the applicable points detailed in the [standard deprecation docs](/general/development/policies/deprecation)) create a `FUNCTIONNAME_is_deprecated()` method in your external function class. Return true if the external function is deprecated. This is an example:
+
+```php
+ /**
+ * Mark the function as deprecated.
+ * @return bool
+ */
+ public static function execute_is_deprecated() {
+ return true;
+ }
+```
+
+## See also
+
+- [Web services developer documentation](./index.md)
+- [Web services user documentation](https://docs.moodle.org/en/Web_services)
+- [Implement a web service client](https://docs.moodle.org/dev/Creating_a_web_service_client)
+- Code example: [Adding a web service, using APIs](https://gist.github.com/timhunt/51987ad386faca61fe013904c242e9b4) by (Tim Hunt)
+Specification:
+- [External services security](./security.md)
+- [External services description](./description.md)
+- [Session locks#Read only sessions in web services](https://docs.moodle.org/dev/Session_locks#Read_only_sessions_in_web_services)
diff --git a/versioned_docs/version-5.1/apis/subsystems/favourites/index.md b/versioned_docs/version-5.1/apis/subsystems/favourites/index.md
new file mode 100644
index 0000000000..a8b333a5b9
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/favourites/index.md
@@ -0,0 +1,132 @@
+---
+title: Favourites API
+tags:
+ - API
+ - core_favourites
+---
+
+## Overview
+
+### What is a favourite?
+
+The favourites API allows you to mark items as favourites for a given user. Marking an item as a favourite is akin to adding a web page to your browser favourites (or bookmarks), or marking someone in your contacts as a favourite. The API provides a means to create, read and delete favourite items, allowing any component to favourite arbitrary items as they see fit.
+
+### What can be marked as a favourite?
+
+Almost any 'item' can be marked as a favourite, provided it is something which can be identified by a unique integer id.
+
+### Identifying items
+
+In order to store a favourite, and be able to uniquely identify it for later retrieval, 4 fields are required. These are: **component**, **itemtype**, **itemid** and **contextid**. You will see these in a range of API calls.
+
+The **itemid** is a unique integer identifier of the item itself. This might be a course id, or conversation id, or the id of any entity in Moodle. In fact, it does not have to be the id of a record from the database either; it can be any arbitrary id, so long as the component storing the item knows what it represents.
+
+The two fields **component** and **itemtype** make up a pairing representing the *type* of each favourite. Within this pair, the **component** must be a valid [frankenstyle](/general/development/policies/codingstyle/frankenstyle) component name and is the name of the component wishing to set/unset the item as a favourite. The **itemtype** can be any identifying string, provided it is unique within the respective component. The type pairing allows us to distinguish between favourites of different types (from different areas of Moodle), which may have identical itemid values.
+
+The **contextid** is the id of the context in which the item is being marked as a favourite. For example, a user's course might be marked as a favourite at the course context, whereas a user's conversation with another user might be marked as a favourite at the user context. It's also possible that items of a certain *type* (remember, this is the `{component, itemtype}` pairing) will be marked as favourites in different contexts, based on the context of the item itself. For example, consider the case in messaging, in which we have a group conversation (one which is linked to a course group), and an individual conversation between two users. Setting the group conversation as a favourite would require the course context to be used, whereas doing the same for the individual conversation would require a user context. Which contextid to use is a decision that must be made by the component creating the favourite.
+
+## Using the API
+
+### Getting a service object
+
+Favourites relies on a service layer to provide functionality to consumers. Getting a service object is as simple as using the service factory methods.
+
+Assuming you have a user context, you can get a service scoped to a single user with:
+
+```php
+$ufservice = \core_favourites\service_factory::get_service_for_user_context($usercontext);
+```
+
+The returned `$ufservice` is an object of type \core_favourites\local\service\user_favourite_service.
+
+### Creating a favourite
+
+Let's say we want to set a course as a favourite. Note: In core, this is done by using the favourite *type* {'core_course', 'courses'}.
+
+The service provides the method:
+
+```php
+public function create_favourite(
+ string $component,
+ string $itemtype,
+ int $itemid,
+ \context $context,
+ int $ordering = null
+): favourite;
+```
+
+So, assuming we have the course id and course context, we can create our favourite with:
+
+```php
+$favourite = $ufservice->create_favourite('core_course', 'courses', $course->id, $coursecontext);
+```
+
+The returned $favourite is an object of type \core_favourites\local\entity\favourite.
+
+### Reading favourites
+
+There are several read actions supported by the service object.
+
+```php
+public function count_favourites_by_type(string $component, string $itemtype, \context $context = null) : int;
+public function find_favourites_by_type(string $component, string $itemtype, int $limitfrom = 0, int $limitnum = 0) : array;
+public function favourite_exists(string $component, string $itemtype, int $itemid, \context $context) : bool;
+public function get_favourite(string $component, string $itemtype, int $itemid, \context $context) : favourite;
+```
+
+### Deleting a favourite
+
+The service provides the method:
+
+```php
+public function delete_favourite(string $component, string $itemtype, int $itemid, \context $context);
+```
+
+So, assuming we have the course id and course context, we can remove the favourite with:
+
+```php
+$ufservice = \core_favourites\service_factory::get_service_for_user_context($usercontext);
+$ufservice->delete_favourite('core_course', 'courses', $course->id, $coursecontext);
+```
+
+### Including favourites in external queries
+
+Most of the time, you should ask the service to find favourite items for you. Sometimes, however, rather than fetching the favourites from the service, you'll just want to include the relevant information in those records from an existing query. You might want to do this if dealing with performance sensitive code where additional queries are undesirable.
+
+The service lets you do this too, by providing the method:
+
+```php
+public function get_join_sql_by_type(string $component, string $itemtype, string $tablealias, string $joinitemid) : array;
+```
+
+which can be used in such cases.
+
+For example, and for simplicity, let's say we have a query returning the ids and names of all courses within a given course category:
+
+```php
+$sql = "SELECT c.id, c.name
+ FROM {course} c
+ WHERE c.category = :category";
+$params = ['category' => 3];
+
+$courses = $DB->get_records_sql($sql, $params);
+```
+
+we can then modify this using the get_join_sql_by_type() result to include favourite information.
+
+```php
+$ufservice = \core_favourites\service_factory::get_service_for_user_context($usercontext);
+list($favsql, $favparams) = $ufservice->get_join_sql_by_type('core_course', 'courses', 'favalias', 'c.id');
+
+$sql = "SELECT c.id, c.name, favalias.id as favouriteid
+ FROM {course} c
+ $favsql
+ WHERE c.category = :category";
+$params = ['category' => 3] + $favparams;
+
+$courses = $DB->get_records_sql($sql, $params);
+```
+
+We've now included id of the favourite in the results via a LEFT JOIN, so as to preserve the original set of records.
+
+If you wish to select ONLY favourites, adding `"AND favouriteid IS NOT NULL"` to the query will achieve this.
diff --git a/versioned_docs/version-5.1/apis/subsystems/files/browsing.md b/versioned_docs/version-5.1/apis/subsystems/files/browsing.md
new file mode 100644
index 0000000000..b5c1961d2f
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/files/browsing.md
@@ -0,0 +1,45 @@
+---
+title: File Browser API
+tags:
+ - File API
+ - Files
+---
+
+The File Browser API is a supplemental API which can be used to fetch information relating to Files stored in the [Moodle File API](./index.md).
+
+### Fetch a series of breadcrumbs to the requested file
+
+This example demonstrates using the `filebrowser` API to fetch the parent folders of a file.
+
+```php
+public function get_file_breadcrumbs(\stored_file $file): ?array {
+ $browser = get_file_browser();
+ $context = get_system_context();
+
+ $fileinfo = $browser->get_file_info(
+ \context::instance_by_id($file->get_contextid()),
+ $file->get_component(),
+ $file->get_filearea(),
+ $file->get_itemid(),
+ $file->get_filepath(),
+ $file->get_filename()
+ )
+
+ if ($fileinfo) {
+ // Build a Breadcrumb trail
+ $level = $fileinfo->get_parent();
+ while ($level) {
+ $path[] = [
+ 'name' => $level->get_visible_name(),
+ ];
+ $level = $level->get_parent();
+ }
+
+ $path = array_reverse($path);
+
+ return $path;
+ }
+
+ return null;
+}
+```
diff --git a/versioned_docs/version-5.1/apis/subsystems/files/converter.md b/versioned_docs/version-5.1/apis/subsystems/files/converter.md
new file mode 100644
index 0000000000..d94913d117
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/files/converter.md
@@ -0,0 +1,98 @@
+---
+title: File Converters
+tags:
+ - File
+ - core_file
+ - file_converter
+ - API
+ - PDF
+ - Conversion
+ - Document
+---
+
+Users are able to submit a wide range of files, and it is a common requirement to convert these to alternative formats.
+
+The most obvious example of this in Moodle core is in the `assignfeedback_editpdf` plugin which allows for conversion from a variety of document types into PDF to facilitate annotation.
+
+The file converters distributed with Moodle currently are:
+
+- Unoconv
+- Google Drive
+
+The file converter API allows for conversion via multiple plugins and will automatically fallback to another suitable plugin upon failure.
+
+The API is designed to be called asynchronously as many cloud services offering document conversion offer an asynchronous API themselves.
+
+## Using the file converter API
+
+A file conversion is performed by the `core_files\converter` API and a single conversion is represented by the `core\files\conversion` class.
+
+Individual file conversions should always be accessed by the `core_files\converter` API.
+
+A file conversion is fetched or created by calling the `start_conversion` function on the converter API and passing in an existing `stored_file` record, along with the target format.
+
+```php title="Starting a new conversion"
+$converter = new \core_files\converter();
+$conversion = $converter->start_conversion($file, 'pdf');
+```
+
+If an existing file conversion matching the file and target format exists, the conversion record for this file will be returned, otherwise a new conversion is created and returned.
+
+To force a fresh conversion, a third boolean parameter can be passed, though this should not normally be necessary.
+
+```php title="Forcing a conversion to be performed again"
+$converter = new \core_files\converter();
+$conversion = $converter->start_conversion($file, 'pdf', true);
+```
+
+### Polling for updates on an existing conversion
+
+When the `start_conversion` function is called, it automatically polls for any update on the conversion so it should not normally be necessary to poll the status separately.
+
+It is however possible to do so:
+
+```php title="Polling the API for the status of a conversino"
+$converter = new \core_files\converter();
+$conversion = $converter->start_conversion($file, 'pdf');
+$converter->poll_conversion($conversion);
+```
+
+### Checking status of a conversion
+
+File conversions can have one of four states:
+
+- `STATUS_PENDING` - The conversion has not yet started;
+- `STATUS_IN_PROGRESS` - A conversion has been picked up by a file converter and is currently in progress;
+- `STATUS_COMPLETE` - The conversion was successful and the converted file is available; and
+- `STATUS_FAILED` - All attempts to convert the file have failed.
+
+The conversion API provides a way to check the status of the conversion with the `$conversion->get_status()` function:
+
+```php title="Fetching status"
+$converter = new \core_files\converter();
+$conversion = $converter->start_conversion($file, 'pdf');
+
+switch ($conversion->get_status()) {
+ case \core_files\conversion::STATUS_COMPLETE:
+ // The file is ready. Do something with it.
+ case \core_files\conversion::STATUS_PENDING:
+ case \core_files\conversion::STATUS_IN_PROGRESS:
+ // Conversion still ongoing. Display spinner to the user.
+ case \core_files\conversion::STATUS_FAILED:
+ // Permanent failure - handle to the user.
+}
+```
+
+### Fetching the target file
+
+Following a conversion, the target file is stored as a `stored_file` record and can be fetched for consumption elsewhere in your API:
+
+```php title="Fetching the new file"
+if ($conversion->get_status() === \core_files\conversion::STATUS_COMPLETE) {
+ $file = $conversion->get_destfile();
+}
+```
+
+## See also
+
+- Creating a new [file converter plugin](../../plugintypes/fileconverter/index.md)
diff --git a/versioned_docs/version-5.1/apis/subsystems/files/index.md b/versioned_docs/version-5.1/apis/subsystems/files/index.md
new file mode 100644
index 0000000000..b17ca0aa59
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/files/index.md
@@ -0,0 +1,438 @@
+---
+title: File API
+tags:
+ - File API
+ - Files
+---
+
+
+
+The File API is used to control, manage, and serve all files uploaded and stored within Moodle. This page covers the core File API, which is responsible for storage, retrieval, and serving of files stored in Moodle.
+
+The following documentation is also related:
+
+- The [Repository API](../../plugintypes/repository/index.md) is responsible for the code paths associated with uploading files to Moodle. This includes Repository plugins.
+- [Using the File API in Moodle forms](../form/usage/files.md)
+- Additional detail of how this API works is discussed in the [File API internals](./internals.md)
+
+## File areas
+
+Files are conceptually stored in _file areas_. A file area is uniquely identified by:
+
+- A `contextid`.
+- A full component name (using the [Frankenstyle](/general/development/policies/codingstyle/frankenstyle)/frankenstyle) format), for example `course`, `mod_forum`, `mod_glossary`, `block_html`.
+- A file area type, for example `intro` or `post`.
+- A unique `itemid`. Typically if there is only one of a file area per context, then the `itemid` is `0`, whilst if there can be multiple instances of a file area within a context, then the id of the item it relates to is used. For example in the course introduction text area, there is only one course introduction per course, so the `itemid` is set to `0`, whilst in a forum each forum post is within the same context, and the `itemid` should be the id of the post that it relates to.
+
+:::note
+
+File areas are not listed separately anywhere, they are stored implicitly in the files table.
+
+:::
+
+:::important Accessing files belonging to another component
+
+Please note that each plugin, or subsystem should only ever access its own file areas. Any other access should be made using that components own APIs. For example a file in the `mod_assign` plugin should only access files within the `mod_assign` component, and no other component should access its files.
+
+:::
+
+### Naming file areas
+
+The names of the file areas are not strictly defined, but it is strongly recommended to use singulars and common names of areas where possible (for example: intro, post, attachment, description).
+
+## Serving files to users
+
+The serving of files to users is separated into two distinct areas:
+
+1. Generating an appropriate URL to the file; and
+2. Parsing the URL to serve the file correctly.
+
+This allows Moodle to have a shared file serving mechanism which is common to all Moodle components.
+
+When serving files you _must_ implement both parts together.
+
+### Generating a URL to your files
+
+You must refer to the file with a URL that includes a file-serving script, often `pluginfile.php`. This is usually generated with the `moodle_url::make_pluginfile_url()` function. For example:
+
+```php title="Generating a pluginfile URL for a known file"
+$url = moodle_url::make_pluginfile_url(
+ $file->get_contextid(),
+ $file->get_component(),
+ $file->get_filearea(),
+ $file->get_itemid(),
+ $file->get_filepath(),
+ $file->get_filename(),
+ false // Do not force download of the file.
+);
+```
+
+:::note
+
+Note: If you do not need the `itemid`, then you _may_ pass a `null` value instead of the `itemid`.
+
+This will remove the `itemid` from the URL entirely - this must be considered when [serving your file to the user](#serving-your-file-to-the-user).
+
+:::
+
+The final parameter (`false` here) is `forcedownload`.
+
+### Serving your file to the user
+
+File serving is performed by a small number of file serving scripts which include:
+
+- `pluginfile.php`; and
+- `tokenpluginfile`.php.
+
+These file serving scripts are responsible for authenticating the user, parsing the URL, and then passing the parameters provided in the URL to the relevant component, via a _callback_, which will then serve the file.
+
+The relevant component is then responsible for finding the file, performing relevant security checks, and finally serving the file to the user.
+
+The component callback _must_ be located in your plugin's `lib.php` file, and _must_ be named `[component]_pluginfile()`. It is passed the following values:
+
+- the context id;
+- the component name;
+- the name of the file area;
+- any item id, if specified in the URL; and
+- the file path and file name.
+
+:::info
+
+The complete function signature for this callback is as follows:
+
+```php
+/**
+ * Serve the requested file for the [component_name] plugin.
+ *
+ * @param stdClass $course the course object
+ * @param stdClass $cm the course module object
+ * @param stdClass $context the context
+ * @param string $filearea the name of the file area
+ * @param array $args extra arguments (itemid, path)
+ * @param bool $forcedownload whether or not force download
+ * @param array $options additional options affecting the file serving
+ * @return bool false if the file not found, just send the file otherwise and do not return anything
+ */
+function [component_name]_pluginfile(
+ $course,
+ $cm,
+ $context,
+ string $filearea,
+ array $args,
+ bool $forcedownload,
+ array $options
+): bool;
+```
+
+
+
+```php title="An empty name is passed to these headings"
+$mform->addElement(
+ 'header',
+ '',
+ get_string('miscellaneoussettings', 'form')
+);
+$mform->addElement(
+ 'select',
+ 'display',
+ get_string('displaymode', 'choice'),
+ $CHOICE_DISPLAY
+);
+$mform->setAdvanced('display');
+
+// Because this section has a non-unique name (an empty string),
+// the advanced flag set for the display element in the previous
+// section will also apply here.
+$mform->addElement(
+ 'header',
+ '',
+ get_string('anothersection', 'form')
+);
+```
+
+
+
+## Marking an entire section as advanced
+
+The `setAdvanced` function can mark an entire section as advanced by specifying the name of the header at the top of the section, for example:
+
+```php title="Marking an entire section as advanced"
+$mform->addElement(
+ 'header',
+ 'miscellaneoussettingshdr',
+ get_string('miscellaneoussettings', 'form')
+);
+$mform->setAdvanced('miscellaneoussettingshdr');
+```
+
+In this example, all fields from this header until the next header will be marked as advanced.
diff --git a/versioned_docs/version-5.1/apis/subsystems/form/advanced/checkbox-controller.md b/versioned_docs/version-5.1/apis/subsystems/form/advanced/checkbox-controller.md
new file mode 100644
index 0000000000..f9890a3e58
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/form/advanced/checkbox-controller.md
@@ -0,0 +1,74 @@
+---
+title: Checkbox controller
+tags:
+ - core_form
+ - core
+ - Forms API
+ - Advanced
+---
+
+The checkbox controller allows developers to group checkboxes together and add a link or button to check, or uncheck, all of the checkboxes at once.
+
+You can add as many groups of checkboxes as you like, as long as they are uniquely named, where the name is an integer.
+
+## Checkbox groups
+
+When adding checkboxes, you can add them in _groups_. Each group of checkboxes must have a unique integer name, for example:
+
+```php title="classes/form/example_form.php"
+public function definition(): void {
+ // These two elements are part of group 1.
+ $mform->addElement('advcheckbox', 'test1', 'Test 1', null, ['group' => 1]);
+ $mform->addElement('advcheckbox', 'test2', 'Test 2', null, ['group' => 1]);
+
+ // Add a checkbox controller for all checkboxes in `group => 1`:
+ $this->add_checkbox_controller(1);
+
+ // These two elements are part of group 3.
+ $mform->addElement('advcheckbox', 'test3', 'Test 3', null, ['group' => 3]);
+ $mform->addElement('advcheckbox', 'test4', 'Test 4', null, ['group' => 3]);
+
+ // Add a checkbox controller for all checkboxes in `group => 3`.
+ // This example uses a different wording isntead of Select all/none by passing the second parameter:
+ $this->add_checkbox_controller(
+ 3,
+ get_string("checkall", "plugintype_pluginname")
+ );
+}
+```
+
+## API
+
+The checkbox controller is described by the following mform function:
+
+```php
+moodleform::add_checkbox_controller(
+ $groupid = null,
+ string $text = null,
+ mixed $attributes = null,
+ int $originalvalue
+): void;
+```
+
+- int *$groupid* This also serves as the checkbox group name. It must be a unique integer per collection of checkboxes.
+- string *$text* (optional) Link display text. Defaults to `get_string('selectallornone', 'form')`.
+- mixed *$attributes* (optional) Either a typical HTML attribute string or an associative array.
+- int *$originalValue* (optional) Defaults to 0; The general original value of the checkboxes being controlled by this element.
+
+:::info An explanation of `$originalvalue`
+
+Imagine that you have 50 checkboxes in your form, which are all unchecked when the form first loads, except 5 or 6 of them.
+
+The logical choice here would be for the standard behaviour to check all of the checkboxes upon first click, then to uncheck them all upon the next click and so on.
+
+If the situation was reversed, with most of the checkboxes already checked by default, then it would make more sense to have the first action uncheck all the checkboxes.
+
+The `$originalvalue` parameter allows you to configure the initial value and therefore the initial behaviour.
+
+:::
+
+### Description of functionality
+
+The first role of the `add_checkbox_controller` method is to add a form element. Depending on whether JavaScript is supported by the browser or not, it will either output a link with onclick behaviour for instant action, or a `nosubmit` button which will reload the page and change the state of the checkboxes, but retain the rest of the data already filled in the form by the user.
+
+The second role is to change the state of the checkboxes. The JavaScript version simply switches all checkboxes to checked or unchecked. The state applied when the link is first clicked depends on the `$originalvalue` parameter as noted above. The non-JavaScript version behaves in exactly the same way, although a page reload is necessary.
diff --git a/versioned_docs/version-5.1/apis/subsystems/form/advanced/no-submit-button.md b/versioned_docs/version-5.1/apis/subsystems/form/advanced/no-submit-button.md
new file mode 100644
index 0000000000..2744b69b20
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/form/advanced/no-submit-button.md
@@ -0,0 +1,54 @@
+---
+title: No submit button
+tags:
+ - core_form
+ - core
+ - Forms API
+ - Advanced
+---
+
+The moodleform 'no_submit_button_pressed()' method allows you to detect if a button on your form has been pressed that is a submit button but that has been defined as a button that doesn't result in a processing of all the form data but will result in some form 'sub action' and then having the form redisplayed. This is useful for example to have an 'Add' button to add some option to a select box in the form etc. You define a button as a no submit button as in the example below (in `definition()`). This example adds a text box and a submit button in a group.
+
+## Form definition
+
+When defining your form, you will need to call the `registerNoSubmitButton()` function with the name of the submit button mark as a non-submission button, for example:
+
+```php
+$mform->registerNoSubmitButton('addtags');
+$tags = [
+ $mform->createElement('text', 'tagsadd', get_string('addtags', 'blog')),
+ $mform->createElement('submit', 'addtags', get_string('add')),
+];
+$mform->addGroup($tags, 'tagsgroup', get_string('addtags','blog'), [' '], false);
+$mform->setType('tagsadd', PARAM_NOTAGS);
+```
+
+## Form handling
+
+When handling a no-submit button press you will need to check whether any no-submit button as pressed _before_ checking for submitted data. For example:
+
+```php
+$mform = new \plugintype_pluginname\form\my_form();
+$mform->set_data($toform);
+
+if ($mform->is_cancelled()){
+ // If you have a cancel button on your form then you will need
+ // to handle the cancel action here according to the
+ // requirements of your plugin
+} else if ($mform->no_submit_button_pressed()) {
+ // If you have a no-submit button on your form, then you can handle that action here.
+ $data = $mform->get_submitted_data();
+} else if ($fromform = $mform->data_submitted()){
+ // This branch is where you process validated data.
+} else {
+ // The form has not been submitted, or was unsuccessfully submitted.
+}
+```
+
+:::important Modifying your form in a no-submit action
+
+Because the check for a no-submit button press takes place on the defined form, the form is already defined at the point that it is checked.
+
+If you wish to add or modify elements or options in your form, then may need to use methods on MoodleQuickForm to redefine your form elements.
+
+:::
diff --git a/versioned_docs/version-5.1/apis/subsystems/form/advanced/repeat-elements.md b/versioned_docs/version-5.1/apis/subsystems/form/advanced/repeat-elements.md
new file mode 100644
index 0000000000..116718e145
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/form/advanced/repeat-elements.md
@@ -0,0 +1,109 @@
+---
+title: Repeat elements
+tags:
+ - core_form
+ - core
+ - Forms API
+ - Advanced
+---
+
+The Form API includes the ability to repeat a group of form elements. This is useful where you need to have an unknown quantity of item data, for example possible answers in a quiz question.
+
+This is achieved by adding a button to the form to handle the creation of the additional buttons using a page reload, and a zero-indexed array added to the `elementname` data returned by `get_data()`.
+
+## Overview
+
+Most of the necessary information is in the phpdoc comment for the repeat_elements() method:
+
+```php
+/**
+ * Method to add a repeating group of elements to a form.
+ *
+ * @param array $elementobjs Array of elements or groups of elements that are to be repeated
+ * @param int $repeats no of times to repeat elements initially
+ * @param array $options a nested array. The first array key is the element name.
+ * the second array key is the type of option to set, and depend on that option,
+ * the value takes different forms.
+ * 'default' - default value to set. Can include '{no}' which is replaced by the repeat number.
+ * 'type' - PARAM_* type.
+ * 'helpbutton' - array containing the helpbutton params.
+ * 'disabledif' - array containing the disabledIf() arguments after the element name.
+ * 'rule' - array containing the addRule arguments after the element name.
+ * 'expanded' - whether this section of the form should be expanded by default. (Name be a header element.)
+ * 'advanced' - whether this element is hidden by 'Show more ...'.
+ * @param string $repeathiddenname name for hidden element storing no of repeats in this form
+ * @param string $addfieldsname name for button to add more fields
+ * @param int $addfieldsno how many fields to add at a time
+ * @param string $addstring name of button, {no} is replaced by no of blanks that will be added.
+ * @param bool $addbuttoninside if true, don't call closeHeaderBefore($addfieldsname). Default false.
+ * @param string $deletebuttonname if specified, treats the no-submit button with this name as a "delete element" button in each of the elements.
+ * @return int no of repeats of element in this page
+ */
+```
+
+## Configuration
+
+- The list of elements you wish to repeat is set in the `$elementobjs` array, with any options passed into the `$options` array.
+A `{no}` placeholder can be placed into strings, such as the element label or default values, to represent the item number.
+
+:::note
+
+While the elements are zero-indexed, the `{no}` label is one-indexed.
+
+:::
+
+- The number of repeats to show initially can be configured using the `$repeats` parameter.
+- The number of elements to add when adding more options is configured using the `$addfieldsno` parameter.
+- The label used for the 'Add more' button can be set using the `$addstring` parameter. A `{no}` placeholder can be used in the string to indicate how many repeats will be added.
+- The number of element repeats currently shown is stored in a hidden element, whose name can be specified using the `$repeathiddenname` parameter.
+
+The following example shows how `repeat_elements()` can be used within a form definition with a delete button for each repeated field :
+
+```php title="definition() function"
+$repeatarray = [
+ $mform->createElement('text', 'option', get_string('optionno', 'choice')),
+ $mform->createElement('text', 'limit', get_string('limitno', 'choice')),
+ $mform->createElement('hidden', 'optionid', 0),
+ $mform->createElement('submit', 'delete', get_string('deletestr', 'choice'), [], false),
+];
+
+
+if ($this->_instance){
+ $repeatno = $DB->count_records('choice_options', ['choiceid' => $this->_instance]);
+ $repeatno += 2;
+} else {
+ $repeatno = 5;
+}
+
+$repeateloptions = [
+ 'limit' => [
+ 'default' => 0,
+ 'disabledif' => array('limitanswers', 'eq', 0),
+ 'rule' => 'numeric',
+ 'type' => PARAM_INT,
+ ],
+ 'option' => [
+ 'helpbutton' => [
+ 'choiceoptions',
+ 'choce',
+ ]
+ ]
+];
+
+$mform->setType('option', PARAM_CLEANHTML);
+$mform->setType('optionid', PARAM_INT);
+
+$this->repeat_elements(
+ $repeatarray,
+ $repeatno,
+ $repeateloptions,
+ 'option_repeats',
+ 'option_add_fields',
+ 3,
+ null,
+ true,
+ 'delete',
+);
+```
+
+For other examples, have a look at the question type editing forms. They make extensive use of repeat_elements().
diff --git a/versioned_docs/version-5.1/apis/subsystems/form/fields/_category_.yml b/versioned_docs/version-5.1/apis/subsystems/form/fields/_category_.yml
new file mode 100644
index 0000000000..5f7a811318
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/form/fields/_category_.yml
@@ -0,0 +1 @@
+label: Form fields
diff --git a/versioned_docs/version-5.1/apis/subsystems/form/fields/choicedropdown.md b/versioned_docs/version-5.1/apis/subsystems/form/fields/choicedropdown.md
new file mode 100644
index 0000000000..bd23fa0988
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/form/fields/choicedropdown.md
@@ -0,0 +1,60 @@
+---
+title: Choice Dropdown
+tags:
+- core_form
+- form
+---
+
+The `choicedropdown` form field creates a dropdown list with multiple options. It is different from a standard select dropdown in that each option can have extra icons and descriptions. This field is often used in forms to facilitate the selection of a non-trivial option that demands additional information.
+
+## Using the `choicedropdown` Form Field
+
+While most form API fields use primitive data types, the `choicedropdown` form field uses a particular data definition called `choicelist`. This data definition is an abstraction that represents a user choice list and is used in other UI components like `core\output\local\dropdown\status` or `core\output\local\action_menu\subpanel`.
+
+The `choicelist` class provides a way to define a list of options with additional information such as icons, descriptions, the currently selected option, or the ability to disable specific options.
+
+## Example Usage
+
+To create a `choicedropdown` form field, you need to:
+
+1. Create a new instance of the `choicelist` class.
+1. Add options and any extra information to the `choicelist` instance.
+1. Add the `choicedropdown` form field to the form, passing the `choicelist` instance.
+
+```php
+// Define the options for the dropdown list.
+$options = new core\output\choicelist();
+$options->add_option(
+ 'option1',
+ "Text option 1",
+ [
+ 'description' => 'Option 1 description',
+ 'icon' => new pix_icon('t/hide', 'Eye icon 1'),
+ ]
+);
+$options->add_option(
+ 'option2',
+ "Text option 2",
+ [
+ 'description' => 'Option 2 description',
+ 'icon' => new pix_icon('t/stealth', 'Eye icon 2'),
+ ]
+);
+$options->add_option(
+ 'option3',
+ "Text option 3",
+ [
+ 'description' => 'Option 3 description',
+ 'icon' => new pix_icon('t/show', 'Eye icon 3'),
+ ]
+);
+
+// Add the choicedropdown field to the form.
+$mform->addElement(
+ 'choicedropdown',
+ 'FIELDNAME',
+ get_string('FIELDNAME', 'PLUGINNAME'),
+ $options,
+);
+$mform->setDefault('FIELDNAME', $defaultvalue);
+```
diff --git a/versioned_docs/version-5.1/apis/subsystems/form/index.md b/versioned_docs/version-5.1/apis/subsystems/form/index.md
new file mode 100644
index 0000000000..68ca4ddbb1
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/form/index.md
@@ -0,0 +1,393 @@
+---
+title: Forms API
+tags:
+ - API
+ - core_form
+ - form
+ - core
+---
+
+Form are created using the Form API. The Form API supports most standard HTML elements, including checkboxes, radio buttons, text boxes, and so on, adding additional accessibility and security features to them.
+
+## Highlights
+
+- Tested and optimised for use on major screen-readers like Dragon and JAWS.
+- Table-less layout.
+- Processes 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 the [File API](../files/index.md) .
+- Support for many custom Moodle specific and non-specific form elements.
+- Facility for [repeated elements](./advanced/repeat-elements.md).
+- Facility for form elements in advanced groups
+
+## Usage
+
+The Moodle forms API separates forms into different areas:
+
+1. a form definition, which extends the `moodleform` class; and
+2. uses of that form.
+
+To create a form in Moodle, you create a class that defines the form, including every form element. Your class must extend the `moodleform` class and overrides the [definition](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29) member function to describe the form elements.
+
+
+In many situations there is not going to be any more to it than that. + +## Ad-hoc Caches + +This is the alternative method of using the cache API.
+It involves creating a cache using just the required params at the time that it is required. It doesn't require that a definition exists making it quicker and easier to use, however it can only use the default settings and is only recommended for insignificant caches (rarely used during operation, never to be mapped or customised, only existing in a single place in code). + +Once a cache object has been retrieved it operates exactly as the same as a cache that has been created for a definition. + +To create an ad-hoc cache you would use the following: + +```php +$cache = cache::make_from_params(cache_store::MODE_APPLICATION, 'mod_myplugin', 'mycache'); +``` + +:::tip + +Don't be lazy, if you don't have a good reason to use an ad-hoc cache you should be spending an extra 5 minutes creating a definition. + +::: + +## The definition + +The above section illustrated how to create a basic definition, specifying just the area name (the key) and the mode for the definition. Those being the two required properties for a definition. + +There are many other options that will let you make the most of the Cache API and will undoubtedly be required when implementing and converting cache solutions to the Cache API. + +The following details the options available to a definition and their defaults if not applied: + +```php +$definitions = [ + // The name of the cache area is the key. The component/plugin will be picked up from the file location. + 'area' => [ + 'mode' => cache_store::MODE_*, + 'simplekeys' => false, + 'simpledata' => false, + 'requireidentifiers' => ['ident1', 'ident2'], + 'requiredataguarantee' => false, + 'requiremultipleidentifiers' => false, + 'requirelockingread' => false, + 'requirelockingwrite' => false, + 'requirelockingbeforewrite' => false, + 'maxsize' => null, + 'overrideclass' => null, + 'overrideclassfile' => null, + 'datasource' => null, + 'datasourcefile' => null, + 'staticacceleration' => false, + 'staticaccelerationsize' => null, + 'ttl' => 0, + 'mappingsonly' => false, + 'invalidationevents' => ['event1', 'event2'], + 'canuselocalstore' => false + 'sharingoptions' => cache_definition::SHARING_DEFAULT, + 'defaultsharing' => cache_definition::SHARING_DEFAULT, + ], +]; +``` + +### Setting requirements + +The definition can specify several requirements for the cache. + +This includes identifiers that must be provided when creating the cache object, that the store guarantees data stored in it will remain there until removed, a store that supports multiple identifiers, and finally read/write locking. + +The options for these are as follows: + +- `simplekeys`: [bool] Set to true if your cache will only use simple keys for its items.
+Simple keys consist of digits, underscores and the 26 chars of the english language. `a-zA-Z0-9_`
+If true the keys won't be hashed before being passed to the cache store for gets/sets/deletes.
It will be better for performance and possible only because we know the keys are safe. +- `simpledata`: [bool] If set to true we know that the data is scalar or array of scalar.
If true, the data values will be stored as they are. Otherwise they will be serialised first. +- `requireidentifiers`: [array] An array of identifiers that must be provided to the cache when it is created. +- `requiredataguarantee`: [bool] If set to true then only stores that can guarantee data will remain available once set will be used. +- `requiremultipleidentifiers`: [bool] If set to true then only stores that support multiple identifiers will be used. +- `requirelockingread`: [bool] If set to true then a lock will be gained before reading from the cache store. It is recommended not to use this setting unless 100% absolutely positively required. +- `requirelockingbeforewrite`:[bool] If set to true then a lock must be gained and held during expensive computation such as the generation of modinfo before writing to the cache store by the calling code. This is to prevent cache stampedes. After gaining the lock code must check to ensure the cache hasn't already been updated by another process. This is so far only used by course `modinfo` application caches presently. + +### Cache modifiers + +You are also to modify the way in which the cache is going to operate when working for your definition. + +By enabling the static option the Cache API will only ever generate a single cache object for your definition on the first request for it, further requests will be returned the original instance + +This greatly speeds up the collecting of a cache object. + +Enabling persistence also enables a static store within the cache object, anything set to the cache, or retrieved from it will be stored in that static array for the life of the request. +This makes the persistence options some of the most powerful. If you know you are going to be using you cache over and over again or if you know you will be making lots of requests for the same items then this will provide a great performance boost. + +Of course the static storage of cache objects and of data is costly in terms of memory and should only be used when actually required, as such it is turned off by default. +As well as persistence you can also set a maximum number of items that the cache should store (not a hard limit, its up to each store) and a time to live (ttl) although both are discouraged as efficient design negates the need for both in most situations. + +- `staticacceleration`: [bool] This setting does two important things. First it tells the cache API to only instantiate the cache structure for this definition once, further requests will be given the original instance.
Second the cache loader will keep an array of the items set and retrieved to the cache during the request.
This has several advantages including better performance without needing to start passing the cache instance between function calls, the downside is that the cache instance + the items used stay within memory.
Consider using this setting when you know that there are going to be many calls to the cache for the same information or when you are converting existing code to the cache and need to access the cache within functions but don't want to add it as an argument to the function. +- `staticaccelerationsize`: [int] This supplements the above setting by limiting the number of items in the caches persistent array of items.
Tweaking this setting lower will allow you to minimise the memory implications above while hopefully still managing to offset calls to the cache store. +- `ttl`: [int] A time to live for the data (in seconds). It is strongly recommended that you don't make use of this and instead try to create an event driven invalidation system (even if the event is just time expiring, better not to rely on `ttl`).
Not all cache stores will support this natively and there are undesired performance impacts if the cache store does not. +- `maxsize`: [int] If set this will be used as the maximum number of entries within the cache store for this definition.
It's important to note that cache stores don't actually have to acknowledge this setting or maintain it as a hard limit. +- `canuselocalstore`: [bool] This setting specifies whether the cache can safely be local to each frontend in a cluster which can avoid latency costs to a shared central cache server. The cache needs to be carefully written for this to be safe. It is conceptually similar to using `$CFG->localcachedir` (can be local) vs `$CFG->cachedir` (must be shared). Look at `purify_html()` in `lib/weblib.php` for an example. + +### Overriding a cache loader + +:::danger + +This is a super advanced feature and should not be done. Ever. Unless you have a very good reason to do so. + +::: + +It allows you to create your own cache loader and have it be used instead of the default cache loader class. The cache object you get back from the make operations will be an instance of this class. + +- `overrideclass`: [string] A class to use as the loader for this cache. This is an advanced setting and will allow the developer of the definition to take 100% control of the caching solution.
Any class used here must inherit the `cache_loader` interface and must extend default cache loader for the mode they are using. +- `overrideclassfile`: [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required. + +### Specifying a data source + +This is a great wee feature, especially if your code is object orientated. + +It allows you to specify a class that must inherit the `cache_data_source` object and will be used to load any information requested from the cache that is not already being stored. + +When the requested key cannot be found in the cache the data source will be asked to load it. The data source will then return the information to the cache, the cache will store it, and it will then return it to the user as a request of their get request. Essentially no get request should ever fail if you have a data source specified. + +- `datasource`: [string] A class to use as the data loader for this definition.
Any class used here must inherit the cache_data_source interface. +- `datasourcefile`: [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required. + +:::note + +In Moodle versions prior to 3.8.6 and 3.9.3, if caching is disabled then *nothing* will be loaded through the data source which is probably not what you expect (rather than the data source being loaded every time but never cached). See also: [MDL-42012](https://moodle.atlassian.net/browse/MDL-42012) + +::: + +### Misc settings + +The following are stand along settings that don't fall into any of the above categories. + +- `invalidationevents`: [array] An array of events that should cause this cache to invalidate some or all of the items within it. Note that these are NOT normal moodle events and predates the [Events API](https://docs.moodle.org/dev/Events_API). Instead these are arbitrary strings which can be used by `cache_helper::purge_by_event('changesincoursecat');` to mark multiple caches as invalid at once without the calling code knowing which caches are affected. +- `mappingsonly`: [bool] If set to true only the mapped cache store(s) will be used and the default mode store will not. This is a super advanced setting and should not be used unless absolutely required. It allows you to avoid the default stores for one reason or another. +- `sharingoptions`: [int] The sharing options that are appropriate for this definition. Should be the sum of the possible options. +- `defaultsharing`: [int] The default sharing option to use. It's highly recommended that you don't set this unless there is a very specific reason not to use the system default. + +## Localized stores for distributed high performance caching + +Most cache definitions are simple in that the code expects to be able to purge the cache, or update it, and for this to be universally available from then on to all code which loads from this cache again. But as you scale up having a single mega shared cache store doesn't work well for a variety of reasons, including extra latency between multiple front ends and the shared cache service, the number of connections the cache server can handle, the cost of IO between services, and depending on the cache definition issues with locking while writing. + +So if you want very high performance caching then you need to write you code so that it can support being distributed, or localized, which means that each front end can have it's own independent cache store. But this architecture means that you have no direct way to communicate from code running in one place to invalidate the caches on all the other front ends. In order to achieve this you need to carefully construct cache keys so that if the content changes then it uses a new cache key, which will of course be a cache miss and then it will regenerate using fresh data. There are multiple ways to achieve this, a couple common example strategies are below. + +### When should you localize? + +Not all caches are good candidates to localize and some can have a detrimental effect if localized for the wrong reasons. + + +### Revision numbers as key suffix + +A simple method is storing a version number somewhere and appending that to your key. This is the most common method used in Moodle, simply store a number somewhere which is globally shared such as in a custom database field, or using `set_config` / `get_config`. + +One small edge case with this approach is you now need to make sure that the incrementing code is atomic, which means you should use a DB transaction, or gain a lock, before bumping the version so you don't get two conflicting changes ending up on the same version with a race condition. However if you are anticipating high turnover rate of the cache you probably have a deeper issue, see 'Fast churning keys' below. + +One potential benefit of a simple version number strategy if your cache misses are very expensive, is that you can check for the presence of a version, and if it doesn't exist it is easy to simply retrieve the previous version and use it in the mean time, while you could generate the new version asynchronously. This is an advanced concept and depends on the use case and has the obvious disadvantage of showing stale data. + +:::info + +An example of this strategy in Moodle is the theme versions cache: https://github.com/moodle/moodle/blob/main/lib/outputlib.php#L88-L100 + +Note this is not actually in MUC but the caching concepts are the same. + +::: + +It works best with a cache store that supports Least Recently Used garbage collection. + +### Revision numbers as value suffix instead of key suffix + +This is conceptually the same as above but has two important differences. Firstly because the key itself is always the same then only a single version of some value will be stored on disk or in memory for any given cache store which makes it much more efficient in terms of storage. But secondly this comes with a higher coding complexity cost because it will no longer be guaranteed to be correct because a local cache could return a hit with a stale version. So if you need it to be correct you will need to parse out the revision from the value and then confirm the revision is correct before using the value. If it is invalid then you need to treat it as a miss and handle that. One way is to rebuild and set it, but this loses the advantage of primary and final caches (see below). A better way is to delete the local cache but not the final cache by passing a second param of false to delete, and then getting the value again which will repopulate the local cache from the shared cache: + +```php + $cache->delete('foo', false); // Delete the primary / local stale version + $cache->get('foo'); // Get the final / shared version (which may also be stale!) +``` + +But this also is imperfect if there are 3 layers of caching, see [MDL-72837](https://moodle.atlassian.net/browse/MDL-72837) for a full discussion and a possible new api to handle this. + +This method is how the course modinfo cache is localized. + +### Using time as a key suffix + +Another common approach is to use a timestamp, this is how some of the core cache numbers work, see `increment_revision_number()` for some examples. This has the benefit of not needing any transaction or locking, but you do run the risk of two processes clashing if they happen to run in the same second. + +It may look like Moodle theme-related caching uses this strategy, but actually if you look at [the code for theme_get_next_revision](https://github.com/moodle/moodle/blob/df0e58adb140f90712bcd3229ad936d3b4bc15d9/lib/outputlib.php#L88), you will see that it is actually guaranteeing to generate a unique new integer which mitigates the clashing mentioned above. It is just making that integer close to current time-stamp, to make it more self-documenting. + +:::info + +https://github.com/moodle/moodle/blob/main/lib/datalib.php#L1131-L1145 + +It works best with a cache store that supports Least Recently Used garbage collection. +::: + +### Content hashes as keys + +A great strategy is to use a digest or hash such as `sha1` / `sha256` of the content stored inside the cache, or in even more advanced scenarios a hash of the dependencies of the content in the cache. This guarantees that the key will be unique, and can be truly distributed without any synchronous communication between the front ends. + +This strategy can work very well when building up large cache items from many smaller cache fragments in a nested tree structure, eg when caching a structure which is built of other cache items, eg 10 chunks of html to get combined into a large chunk to be cached, you would append the 10 hashes of the 10 smaller chunks and then hash that to use as the key for the combined cache item. This means you can mutate a small part of a tree structure and quickly re-generate the whole tree without expensively regenerating all of the other branches and leaves in the tree. + +:::info + +This is known as 'Russian Doll' caching: https://blog.appsignal.com/2018/04/03/russian-doll-caching-in-rails.html + +::: + +This is a very common strategy is many distributed systems, outside of the context of caching, and is conceptually how git works internally which is why commits are a `sha1` hash. + +This strategy works well if you may periodically change back and forth to previous states which will still be present and so be immediate hits without re-warming. It works best with a cache store that supports Least Recently Used garbage collection. + +### Primary and Final caches + +Because HTTP requests are generally assigned randomly or round-robin to front ends, when a cache item version changes you will now effectively have an empty cache on every front end. As you get the same cache item again and again on each front end it will continue to be a cache miss on each local box until they are all warm, which can ironically mean that on average for a fast-changing, but not often requested cache item, your cache hit rate will be very low and much worse than if you had a shared cache. The solution here is to have multiple levels of caches set up, a local cache backed by a shared cache. You do not need to do anything special in the code to support this if your cache is already localizable, the MUC manages this for you, ie if you request a key missing from the local cache it will then request it from the shared cache. If present it will copy it back to the local cache and then return the value. If it is not present in either then your fallback code will generate the item, and it will be written to both cache stores at the same time. + +This is especially important if you are scaling up and down the number of frontends quickly. If you suddenly need more horizontal scale and create a bunch of new front ends with empty caches and no shared cache they will all consume even more resources warming up and loading the shared services such as the database and filesystem. + +A good rule of thumb is to pair similar types of local and shared caches together. For instance, it is very common to store the Moodle string cache in APCu because it is very heavily used, so an in-memory cache is the fastest and is well paired this a shared cache like Redis. `coursemodinfo` on the other hand is often very large so isn't as practical to store in Redis so it is usually cached on disk, so you could have a local file cache (which could often be very fast `SSD`) and pair it with a shared disk cache in `dataroot` (often much slower over `NFS` or `Gluster`). + +As you scale even bigger, a new bottleneck can appear when purging a shared disk cache ie when you deploy a new version. A full purge needs to iterate over and remove and sync a very large number of files, which can take some time. See [MDL-69088](https://moodle.atlassian.net/browse/MDL-69088) for a proposed fix. + +### Beware fast churning keys + +A big concern when designing a cache is how fast you anticipate it changing. If it contains very fast moving data but sparsely requested data (see above) then you can end up in a situation where you are effectively just using the shared final cache, and wasting latency and space and IO cloning data to the local cache where is may not be hit again very much. As always caching is a balancing act trading off between CPU, time and disk, and ultimately money. + +Even if your cache is able to use a local store that doesn't mean it actually will be configured to be local (and your code can't tell either way). So a wasteful cache item will consume much more space storing all the previous versions of its items even if it isn't localized, and it will be much worse if it is. + +### Time-To-Live for distributed caches + +Another consideration is the total size of your cache stores across all the front ends. As cache keys change they are never be invalidated or purged. So you should have in place some process to garbage collect stale items. This is more a concern for the cache store implementations and the configuration but worth considering. Some stores are deleted on upgrade, or have a Time-To-Live or a Least Recently Used strategy for deleting stale items. + +## Miscellaneous + +- Checkout important [discussion about the Cache API at the Moodle developer chat](https://moodle.org/local/chatlogs/index.php?q=cache) diff --git a/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humandate_example.png b/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humandate_example.png new file mode 100644 index 0000000000..89b36a3311 Binary files /dev/null and b/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humandate_example.png differ diff --git a/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humantimeperiod_example.png b/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humantimeperiod_example.png new file mode 100644 index 0000000000..2f92eb67b6 Binary files /dev/null and b/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humantimeperiod_example.png differ diff --git a/versioned_docs/version-5.1/apis/subsystems/output/_inplace/inplace_editable_example.png b/versioned_docs/version-5.1/apis/subsystems/output/_inplace/inplace_editable_example.png new file mode 100644 index 0000000000..e276ade2fa Binary files /dev/null and b/versioned_docs/version-5.1/apis/subsystems/output/_inplace/inplace_editable_example.png differ diff --git a/versioned_docs/version-5.1/apis/subsystems/output/humandate.md b/versioned_docs/version-5.1/apis/subsystems/output/humandate.md new file mode 100644 index 0000000000..d5efbd1e5b --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/output/humandate.md @@ -0,0 +1,77 @@ +--- +title: Date and Time Output Classes +tags: + - Output +--- + +` methods for all renderables used in the plugin. A theme designer can provide a custom version of this renderer that changes the behaviour of any of the render methods and so to customize their theme. In this example, the render method for the index page (`render_index_page`) does 2 things. It asks the renderable to export it's data so that it is suitable for passing as the context to a template, and then renders a specific template with this context. A theme designer could either manipulate the data in the render method (e.g. removing menu entries), or change the template (change the generated HTML) to customize the output.
+
+You do not need to implement a renderer for a plugin if you are using templates and you either:
+
+1. Use the `templatable` interface and have a template with the same name in the same namespace
+2. Use the `named_templatable` interface
+
+In these cases the data from the renderable will be automatically routed to the correct template, however if you do implement a render method that will be used in preference to the default routing.
+
+The template used in this plugin is located in the plugin's templates folder. The template can also be overridden by a theme designer.
+
+```xml title="admin/tool/demo/templates/index_page.mustache"
+
`data-id={SECTION.ID}`
`data-number={SECTION.NUM}` | +| **Section header** | `data-for="section_title"`
`data-id={SECTION.ID}
data-number={SECTION.NUM}` | +| **Course module item (activity)** | `data-for="cmitem"`
`data-id={CM.ID}` | +| **Course sections list** | `data-for="course_sectionlist"` | +| **Section course modules list** | `data-for="cmlist"` | +| **Course module action link** | `data-action={ACTIONNAME}`
`data-id={CM.ID}` | +| **Section action link** | `data-action={ACTIONNAME}`
`data-id={SECTION.ID}` | +| **Section info** | `data-for="sectioninfo"` | + +## Implementing format specific actions + +All course editing actions done by the user will trigger what is called "state actions" that will update the backend, but also send back information on how to update the frontend in real time. The core state actions are defined in the `core_courseformat\stateactions` class. However, each format plugin extend this class to add its own actions by placing them in the `course/format/PLUGINNAME/classes/courseformat/stateactions.php` file. + +All state action will receive the same parameters: + +- `stateupdates $updates` an object to register the state updates. This object will be used to inform the frontend about the changes. +- `stdClass $course` the course object +- `int[]` $ids the list of affected ids. They could be cmids or section ids depending on the action. +- `int $targetsectionid` optional target section id. For example, when moving a course module to a new section. +- `int $targetcmid` optional target cm id. For example, when moving a course module to a new position. + +The best example on how to implement a state action is to look at the `format_topics\courseformat\stateactions` class (located at `course/format/topics/classes/courseformat/stateactions.php`). The topics format incorporate two new state actions: `section_highlight` and `section_unhighlight`. + +Once your plugin has the integration class implemented with all the extra actions, the action will be available to be executed by the user. + +### Execute format specific action from the course page via Ajax + +Once the format provides a state action, the plugin must inform the frontend about the new action. + +As explained in previous sections, the course editor uses a reactive pattern to keep the course updated. The course editor will always modify the UI to represent the current state data. When a user executes an action, the course editor will send the action to the backend, wait for the state updates, and apply then to the frontend state data. This is what is known as `mutation`. + +The `mutations` is the only way to execute state actions from the frontend, and each plugins that implements new state actions in the backend must provide a mutation to the frontend. + +Once again, the best example on how to implement a mutation is to look at the `course/format/topics/amd/src/mutations.js`. The topics format incorporate two new mutations: `sectionHighlight` and `sectionUnhighlight`. + +The JavaScript reactive components can execute the mutation using the `this.reactive.dispatch` method. + +### Execute state actions via non-AJAX requests + +
- core_courseformat/local/courseeditor: coordinates all the UI elements via a data structure called "reactive state data" (or simply, "state data").
- core_courseformat/local/courseeditor/mutations: centralizes all the backend calls and applies the results to the reactive state data before the UI components update the interface.
- core_courseformat/local/content/actions: captures the user clicks on specific action links and displays modals to get more information from the user if necessary (for example the destination position in a move activity action).
- core_courseformat/content/\*: ADM modules responsible for keeping some part of the UI aligned with the reactive state data.
- core_courseformat/courseeditor/\*: other modules and helpers
NOTE: some user actions like hiding and showing sections/activities are not yet migrated to the new architecture.
NOTE: updating a full section or activity HTML is still handled by the core_course/actions module. However, now both methods are public to the module and they are used by the new course editor.
| +| course/dndupload.js file is responsible for handling any file dropping on the course page. | Moodle 4.0 still uses the course/dndupload.js to handle files dropped into the course area. | +| The webservice core_course_edit_section is responsible for updating a course section and returning the section header and the activities list HTML. |Except for showing and hiding a section (not migrated yet) the rest of the section actions are now handled by the new `core_courseformat_update_course` webservice.
The new webservice has the same parameters for both section and activity actions and always returns a standardized data structure to interact with the frontend reactive state data. This means that it does not return HTML fragments anymore.
| +| The webservice core_course_edit_module is responsible for updating activity and returning the activity HTML or other page fragments. |Except for showing and hiding an activity (not migrated yet) the rest of the activity actions are now handled by the new `core_courseformat_update_course` webservice.
The new webservice has the same parameters for both section and activity actions and always returns a standardized data structure to interact with the frontend reactive state data. This means that it does not return HTML fragments anymore.
| +| All frontend JS logic is responsible for interacting with the backend and updating all the necessary frontend elements depending on the return value. |The JS logic is now distributed into several modules called "components". Each module can only interact with a specific page element and watch a data structure called reactive state date (or simply "state data").
The main points of the new component structure are:
- The initial state data is loaded using the `core_courseformat_get_state` webservice
- All components are registered into the core_courseformat/courseeditor page instance.
- When the state data changes, the course editor instance triggers the component's watchers methods to update the UI.
- Components are not able to alter the state data. If a component captures an action that requires some state change, it asks the course editor to perform a state mutation.
Most renderer methods are now deprecated and have been migrated to output classes and mustache templates. There are only a few rendered methods formats that can override.
Now format plugins can override output classes by simply creating the equivalent format_pluginname/output/courseformat/* class. For example, core_courseformat\output\local\content can be overridden by creating a format_pluginname\output\courseformat\content class.
Important note: the new mustache structure uses partials and blocks to include sub-templates. This opens the door to a future frontend course rendering but it also makes the template overriding a bit more complex. See the "overriding templates" section for more information.
| +|Format renderer is optional. If none is provided the course format renderer_base is used.
Inside a format rendered the `$this->courserenderer` attribute is used to access the course renderer methods.
| Format renderer is mandatory. The base core_courseformat\output\section_renderer now extends the core_course_renderer class and `$this->courserenderer` is deprecated. | +| The page elements are located using css class names such as "li.activity", ".actions", or "li.section". | All page elements are now located using data attributes. See [Course elements data attributes](./index.md#course-elements-data-attributes) for more information. | +| The course is rendered using print_single_section_page or print_multiple_section_page depending on the number of sections to render. |The course format base instance contains all the necessary data to determine the way a course is rendered. To Specify a single section page formats should use `$format->set_section_number` method before rendering the course.
Once the format instance setup is finished, the course is rendered using the `content` output class. See migrating old renderer methods to outputs section for more information.
| +| To know if the user is editing the course, the format should check for `$PAGE->user_is_editing()` to know if edit is enabled and also `has_capability('moodle/course:update', $coursecontext)` to know if the user has the required capabilities. | The format base class have a method `$format->show_editor()` that do all the user and page validations to know if the current course display has to include editor options or not. | + +The following diagram represents the data flow of the new architecture: + + + +## First steps to migrate a 3.11 course format to 4.0 + +From 4.0 the course/format folder has its own subsystem called core_courseformat. This subsystem contains all the course rendering logic (only some minor elements are still in the original location for retro compatibility until Moodle 4.3). + +To ensure your format plugin is integrated with the new subsystem: + +- The main format_pluginname class should extend `core_courseformat\base` instead of the old format_base one. +- Your plugin **must provide a renderer class**. In most cases this class **will extend `core_courseformat\output\section_renderer`**. +- Any output class your plugin needs to override should be located in format_pluginname/classes/output/courseformat + +In summary, the first two things you need to adapt to your format are: + +### Point 1: create a renderer class + +Now renderer classes are mandatory for course format plugins. Here there are two scenarios: + +Scenario 1: if you plugin already has one you should replace the old "extends format_section_renderer_base" by "extends core_courseformat\output\section_renderer". + +Scenario 2: If your plugin does not have a renderer, create a file **course/format/pluginname/classes/output/renderer.php** with a content like: + +
+
+
+### Point 2: fix your base class
+
+All Moodle 3.11 formats have a base format class extending format_base class from core_course. In Moodle 4.0 this class has been moved to `core_courseformat\base`. This means that you should replace the existing extends to avoid the deprecation message.
+
+For compatibility reasons, the base class does not use a namespace and should be located in your plugin "lib.php" file. This could change after Moodle 4.3 when most old course rendering methods will be removed from core.
+
+## The new output architecture
+
+When the debug messages are enabled, all 3.11 format plugins will show several deprecation messages. Most of them are due to the fact that almost all previous renderer methods are now deprecated. The full list can be found in the **course/upgrade.txt** file.
+
+Until 3.11 all course page elements are rendered using html_writer inside renderer methods. This made the UI hard to maintain because most of the methods are referring to the standard course structure (section_right_content, section_left_content, start_section_list, end_section_list…) instead of generic concepts like sections, activities, or activity menu.
+
+With the new architecture, almost all UI elements are rendered using:
+
+- An **output class** that generates the data to render. For example, course/format/classes/output/local/content/section.php
+- A **mustache template** to render output class data. For example, course/format/templates/local/content/section.mustache
+- An optional **reactive component** to update the frontend when the reactive state data changes: For example, course/format/amd/src/local/content/section.js
+
+The following diagram represents the new output structure compared to the 3.11 one:
+
+
+
+## Migrating old renderer methods to outputs
+
+The process of migrating a renderer method to output can be complex depending on the element your format overrides. For these reasons, Moodle 3.11 formats will remain using the old renderer methods until they explicitly use the new outputs.
+
+### Step 1: start using output components and renderers
+
+As in Moodle 3.11 formats, all the course view is initialized and rendered in the "course/format/pluginname/format.php" file. However, the way the outputs are initialized is quite different from the previous version.
+
+In Moodle 3.11 the format.php process was something like:
+
+1. Do some param validations
+2. Get the course format instance using `course_get_format` or `core_courseformat\base::instance`
+3. Get the format/course renderer using: `$PAGE->get_renderer('format_pluginname')`;
+4. Use the renderer `print_single_section_page` or `print_multiple_section_page` depending on the section param.
+
+The problems with that approach were:
+
+- There are two main renderer methods which are almost the same
+- The auxiliary renderer methods require a big amount of params even if they are not needed for the method because they need to provide those parameters to all the child methods.
+
+To avoid this situation now the format base class instance is used as a single exchange param to all output classes. Once the format instance is initialized every output class can get all necessary information from it.
+
+The new workflow in 4.0 is:
+
+View example
+
+
+import Renderer from '!!raw-loader!./_examples/output/renderer.php';
+export const RendererProps = {
+ examplePurpose: 'Output renderer',
+ plugintype: 'format',
+ pluginname: 'pluginname',
+ filepath: '/output/renderer.php',
+};
+
+
+{getExample(RendererProps, Renderer)}
+
+
+
+
+Some important notes about the code:
+
+- The rendered class now can be obtained using `$format->get_renderer`
+- Format plugins can override any core_courseformat output class (see sections below for more details). To get the correct output you need to use `$format->get_output_classname` method.
+- As you may notice, the output class is rendered directly using the render method, not the `render_from_template` one. This is possible because all output classes implement the new Moodle 4.0 `named_templatable` interface.
+
+### Step 2: override any output class to alter the template data to your plugin needs
+
+Instead of having several renderer methods on a single file, the core_courseformat subsystem splits the output logic through several small classes, each one for a specific UI component. Format plugins can easily override specific classes to alter the template data.
+
+The course format base class has a special method called get_output_classname that returns the overridden class name if available in the format plugin, or the core one if not. In order to detect the format classes, your plugin must place the overridden one in your format_pluginname\output\courseformat\...
+
+For example, if a format plugin wants to add new options to the section action menu it should override the core_courseformat\output\local\content\section\controlmenu. To do so the plugin class should be format_topics\output\courseformat\content\section\controlmenu. You can find an example of an overridden output in the "course/format/topics/classes/output/courseformat/content/section/controlmenu.php" file.
+
+### Step 3: create the basic mustache structure
+
+Unlike output classes, mustache files cannot be extended nor overridden. To be able to alter specific mustaches your plugin must provide a minimum template structure. Furthermore, your plugin must provide some overridden output classes providing the alternative mustache templates location.
+
+In moodle 3.11 the course render uses html_writer to generate the course view, where each renderer method has both data collection and HTML generating inside. This is not the case in Moodle 4.0. From now on, the full output data is collected via output classes before rendering all the nested mustache templates.
+
+The course format subsystem requires a minimum of 3 mustaches to render a course:
+
+- **local/content**: the full course template
+- **local/content/section**: a section template. Used to refresh a section via ajax
+- **local/content/section/cmitem**: an activity item template: Used to refresh an activity via ajax
+
+The first thing your plugin needs is to create that structure and link it to the output components. Follow the guide on the [create format plugin page](./index.md#creating-the-basic-output-structure) to know how to create the basic structure.
+
+### Step 4: create your own custom mustache blocks
+
+Once your plugin has the basic mustache structure, you can provide extra mustache blocks to override parts of the page. Follow the [Override mustache blocks](./index.md#override-mustache-blocks) on the Creating a course format page to know how to do it.
+
+## Enabling course index in your format
+
+If your course format plugin uses a sections-activity structure it is possible to enable the course index. Add the course index in your format is as easy as overriding a method on your format base class:
+
+View example
+
+
+import Format from '!!raw-loader!./_examples/format.php';
+export const FormatProps = {
+ examplePurpose: 'Format course display',
+ plugintype: 'format',
+ pluginname: 'pluginname',
+ filepath: '/format.php',
+};
+
+
+{getExample(FormatProps, Format)}
+
+
+
+
+It is important to note that the course index drawer is only available in Boost based themes, Classic based themes won't display it.
+
+See the course index section in the create format plugin page for more information.
+
+## Enabling reactive components
+
+Moodle 4.0 introduced a new reactive course editor for the frontend. However, the new modules are not compatible with the previous YUI ones. To prevent errors in the 3.11 formats the new libraries are opt-in, meaning plugins must adapt their code before using it.
+
+Step 1: add data attributes to the HTML elements
+The previous YUI editor uses CSS classes to identify sections, activities, and section headers. Nowadays, the use of CSS classes beyond styling is discouraged so the new library uses data attributes to identify the main course page elements.
+
+To adapt your plugin to the new editor you must add the proper data attributes. The following table explains the new selectors:
+
+| Concept | 3.11 equivalent | 4.0 data attributes |
+| ---- | ---- | ---- |
+| Section | `li.section#section-{SECTION.NUM}` | `data-for="section"`View example
+
+
+import BaseCourseIndex from '!!raw-loader!./_examples/lib_course_index.php';
+export const BaseCourseIndexProps = {
+ examplePurpose: 'Format base class with course index enabled',
+ plugintype: 'format',
+ pluginname: 'pluginname',
+ filepath: '/lib.php',
+};
+
+
+{getExample(BaseCourseIndexProps, BaseCourseIndex)}
+
+ `data-id={SECTION.ID}`
`data-number={SECTION.NUM}` | +| Section header | `#sectionid-{SECTION.ID}-title` | `data-for="section_title"`
`data-id={SECTION.ID}`
`data-number={SECTION.NUM}` | +| Course module item (activity) | `li.activity#module-{CM.ID}` | `data-for="cmitem"`
`data-id={CM.ID}` | +| Course sections list | `.course-content>ul` | `data-for="course_sectionlist"`
`Section course modules list Li.section .content .section`
`data-for="cmlist"`| +| Course module action link | `a.cm-edit-action` | `data-action={ACTIONNAME}`
`data-id={CM.ID}` | +| Section action link | `.section_action_menu` | `data-action={ACTIONNAME}`
`data-id={SECTION.ID}` | +| Section info | `.section_availability` | `data-for="sectioninfo"` | + +### Step 2: enable supports components feature + +Once your plugin has all the necessary data attributes you can disable the old YUI editor and enable the new reactive one by adding this method to your plugin base class: + +
+
+
+### Step 3: check the reactive components are enabled.
+
+In principle, if you create the basic mustache structure as described in the previous chapter the course editor should work as expected. However, to check if they are working properly:
+
+1. Enable developer debug level on your site and access a course as an administrator
+2. Wait for the page to load and find in the debug footer the "Reactive instances" section.
+3. Click on the button "CourseEditorXXXX" (where XXXX is the current course ID)
+4. Once the panel opens, click on the "Highlight OFF" button (it will change to "Highlight ON")
+5. Go to the top of the page and check the course content has several thick blue borders.
+
+If the border appears around all the course content elements (sections, section headers and activities) means that the course editor has registered all the course content as a reactive component.
+
+If you don't have a "CourseEditorXXXX" button or the content elements don't get highlighted means that, most probably, you override the main content mustache in a peculiar way and removed the JS initialization.
+
+To re-introduce the JS initialization you should edit the plugin's "content.mustache" file with the following:
+
+- Add `id="{{uniqid}}-course-format"` to the course content div element.
+- At the end of the template add:
+
+```handlebars
+{{#js}}
+require(['core_courseformat/local/content'], function(component) {
+ component.init('{{uniqid}}-course-format', {}, {{sectionreturn}});
+});
+{{/js}}
+```
+
+By doing that the content main reactive component should be initialized and if you enable the highlighting the content should have a blue border. If some if the inner elements does not have a blue border when highlight is ON means that some data attribute is missing. Check the step 1 of this chapter for more information.
diff --git a/versioned_docs/version-5.1/apis/plugintypes/index.md b/versioned_docs/version-5.1/apis/plugintypes/index.md
new file mode 100644
index 0000000000..12aaf9f599
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/index.md
@@ -0,0 +1,301 @@
+---
+title: Plugin types
+tags:
+ - Plugins
+ - core
+ - API
+---
+
+Moodle is a powerful, and very extensible, Learning Management System. One of its core tenets is its extensibility, and this is primarily achieved through the development of plugins.
+
+A wider range of plugin types are available and these should be selected depending on your needs.
+
+## 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. Please see the [Plugin files](./commonfiles) documentation that describes common files which are found in many plugin types.
+
+## Naming conventions
+
+Plugins typically have at least two names:
+
+- The friendly name, shown to users, and
+- A machine name used internally.
+
+The machine name must meet the following rules:
+
+- It must start with a lowercase latin letter
+- It may contain only lowercase latin letters, numbers, and underscores
+- It must end with a lowercase latin letter, or a number
+- The hyphen, and minus character `-` are not allowed
+
+If a plugin does not meet these requirements then it will be silently ignored.
+
+:::tip
+
+Plugin name validation takes place in `core_component::is_valid_plugin_name()` and the following regular expression is used:
+
+```
+/^[a-z](?:[a-z0-9_](?!__))*[a-z0-9]+$/
+```
+
+:::
+
+:::danger Activity module exception
+
+The underscore character is not supported in activity modules for legacy reasons.
+
+:::
+
+
+
+| Plugin type | Component name ([Frankenstyle](/general/development/policies/codingstyle/frankenstyle)) | Moodle path | Description | Moodle versions |
+| --- | --- | --- | --- | --- |
+| [Activity modules](./mod/index.mdx) | 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/index.mdx) | 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+ |
+| [Assignment submission plugins](./assign/submission.md) | assignsubmission | /mod/assign/submission | Different forms of assignment submissions | 2.3+ |
+| [Assignment feedback plugins](./assign/feedback.md) | assignfeedback | /mod/assign/feedback | Different forms of assignment feedbacks | 2.3+ |
+| [Book tools](./mod_book/index.md) | booktool | /mod/book/tool | Small information-displays or tools that can be moved around pages | 2.1+ |
+| [Custom fields](./customfield/index.md) | customfield | /customfield/field | Custom field types, used in Custom course fields | 3.7+ |
+| [Database fields](./mod_data/fields.md) | datafield | /mod/data/field | Different types of data that may be added to the Database activity module | 1.6+ |
+| [Database presets](./mod_data/presets.md) | datapreset | /mod/data/preset | Pre-defined templates for the Database activity module | 1.6+ |
+| [LTI sources](https://docs.moodle.org/dev/External_tool_source) | ltisource | /mod/lti/source | LTI providers can be added to external tools easily through the external tools interface see [Documentation on External Tools](https://docs.moodle.org/en/External_tool). This type of plugin is specific to LTI providers that need a plugin that can register custom handlers to process LTI messages | 2.7+ |
+| [File Converters](./fileconverter/index.md) | fileconverter | /files/converter | Allow conversion between different types of user-submitted file. For example from .doc to PDF. | 3.2+ |
+| [LTI services](https://docs.moodle.org/dev/LTI_services) | ltiservice | /mod/lti/service | Allows the implementation of LTI services as described by the IMS LTI specification | 2.8+ |
+| [Machine learning backends](./mlbackend/index.md) | mlbackend | /lib/mlbackend | Prediction processors for analytics API | 3.4+ |
+| [Forum reports](./mod_forum/index.md) | forumreport | /mod/forum/report | Display various reports in the forum activity | 3.8+ |
+| [Quiz reports](https://docs.moodle.org/dev/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](https://docs.moodle.org/dev/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](https://docs.moodle.org/dev/SCORM_reports) | scormreport | /mod/scorm/report | Analysis of SCORM attempts | 2.2+ |
+| [Workshop grading strategies](https://docs.moodle.org/dev/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](https://docs.moodle.org/dev/Workshop) module | 2.0+ |
+| [Workshop allocation methods](https://docs.moodle.org/dev/Workshop_allocation_methods) | workshopallocation | /mod/workshop/allocation | Define ways how submissions are assigned for assessment in the [Workshop](https://docs.moodle.org/dev/Workshop) module | 2.0+ |
+| [Workshop evaluation methods](https://docs.moodle.org/dev/Workshop_evaluation_methods) | workshopeval | /mod/workshop/eval | Implement the calculation of the grade for assessment (grading grade) in the [Workshop](https://docs.moodle.org/dev/Workshop) module | 2.0+ |
+| [Blocks](./blocks/index.md) | block | /blocks | Small information-displays or tools that can be moved around pages | 2.0+ |
+| [Question types](https://docs.moodle.org/dev/Question_types) | qtype | /question/type | Different types of question (for example multiple-choice, drag-and-drop) that can be used in quizzes and other activities | 1.6+ |
+| [Question behaviours](https://docs.moodle.org/dev/Question_behaviours) | qbehaviour | /question/behaviour | Control how student interact with questions during an attempt | 2.1+ |
+| [Question import/export formats](https://docs.moodle.org/dev/Question_formats) | qformat | /question/format | Import and export question definitions to/from the question bank | 1.6+ |
+| [Text filters](./filter/index.md) | filter | /filter | Automatically convert, highlight, and transmogrify text posted into Moodle. | 1.4+ |
+| [Editors](./../subsystems/editor/index.md) | editor | /lib/editor | Alternative text editors for editing content | 2.0+ |
+| [Atto editor plugins](./atto/index.md) | atto | /lib/editor/atto/plugins | Extra functionality for the Atto text editor | 2.7+ |
+| [Enrolment plugins](./enrol/index.md) | enrol | /enrol | Ways to control who is enrolled in courses | 2.0+ |
+| [Authentication plugins](https://docs.moodle.org/dev/Authentication_plugins) | auth | /auth | Allows connection to external sources of authentication | 2.0+ |
+| [Admin tools](/general/projects/api/admin-tools) | tool | /admin/tool | Provides utility scripts useful for various site administration and maintenance tasks | 2.2+ |
+| [Log stores](./logstore/index.md) | logstore | /admin/tool/log/store | Event logs storage back-ends | 2.7+ |
+| [Availability conditions](./availability/index.md) | availability | /availability/condition | Conditions to restrict user access to activities and sections. | 2.7+ |
+| [Calendar types](https://docs.moodle.org/dev/Calendar_types) | calendartype | /calendar/type | Defines how dates are displayed throughout Moodle | 2.6+ |
+| [Messaging consumers](https://docs.moodle.org/dev/Messaging_consumers) | message | /message/output | Represent various targets where messages and notifications can be sent to (email, sms, jabber, ...) | 2.0+ |
+| [Course formats](./format/index.md) | format | /course/format | Different ways of laying out the activities and blocks in a course | 1.3+ |
+| [Data formats](https://docs.moodle.org/dev/Data_formats) | dataformat | /dataformat | Formats for data exporting and downloading | 3.1+ |
+| [User profile fields](https://docs.moodle.org/dev/User_profile_fields) | profilefield | /user/profile/field | Add new types of data to user profiles | 1.9+ |
+| [Reports](https://docs.moodle.org/dev/Reports) | report | /report | Provides useful views of data in a Moodle site for admins and teachers | 2.2+ |
+| [Course reports](https://docs.moodle.org/dev/Course_reports) | coursereport | /course/report | Reports of activity within the course | Up to 2.1 (for 2.2+ see [Reports](https://docs.moodle.org/dev/Reports)) |
+| [Gradebook export](https://docs.moodle.org/dev/Gradebook_export) | gradeexport | /grade/export | Export grades in various formats | 1.9+ |
+| [Gradebook import](https://docs.moodle.org/dev/Gradebook_import) | gradeimport | /grade/import | Import grades in various formats | 1.9+ |
+| [Gradebook reports](https://docs.moodle.org/dev/Gradebook_reports) | gradereport | /grade/report | Display/edit grades in various layouts and reports | 1.9+ |
+| [Advanced grading methods](https://docs.moodle.org/dev/Grading_methods) | gradingform | /grade/grading/form | Interfaces for actually performing grading in activity modules (for example Rubrics) | 2.2+ |
+| [MNet services](https://docs.moodle.org/dev/MNet_services) | mnetservice | /mnet/service | Allows to implement remote services for the [MNet](https://docs.moodle.org/dev/MNet) environment (deprecated, use web services instead) | 2.0+ |
+| [Webservice protocols](https://docs.moodle.org/dev/Webservice_protocols) | webservice | /webservice | Define new protocols for web service communication (such as SOAP, XML-RPC, JSON, REST ...) | 2.0+ |
+| [Repository plugins](./repository/index.md) | repository | /repository | Connect to external sources of files to use in Moodle | 2.0+ |
+| [Portfolio plugins](https://docs.moodle.org/dev/Portfolio_plugins) | portfolio | /portfolio | Connect external portfolio services as destinations for users to store Moodle content | 1.9+ |
+| [Search engines](https://docs.moodle.org/dev/Search_engines) | search | /search/engine | Search engine backends to index Moodle's contents. | 3.1+ |
+| [Media players](https://docs.moodle.org/dev/Media_players) | media | /media/player | Pluggable media players | 3.2+ |
+| [Plagiarism plugins](https://docs.moodle.org/dev/Plagiarism_plugins) | plagiarism | /plagiarism | Define external services to process submitted files and content | 2.0+ |
+| [Cache store](https://docs.moodle.org/dev/Cache_store) | cachestore | /cache/stores | Cache storage back-ends. | 2.4+ |
+| [Cache locks](https://docs.moodle.org/dev/Cache_locks) | cachelock | /cache/locks | Cache lock implementations. | 2.4+ |
+| [Themes](https://docs.moodle.org/dev/Themes) | theme | /theme | Change the look of Moodle by changing the the HTML and the CSS. | 2.0+ |
+| [Local plugins](./local/index.mdx) | local | /local | Generic plugins for local customisations | 2.0+ |
+| [Content bank content types](https://docs.moodle.org/dev/Content_bank_content_types) | contenttype | /contentbank/contenttype | Content types to upload, create or edit in the content bank and use all over the Moodle site | 3.9+ |
+| [H5P libraries](https://docs.moodle.org/dev/H5P_libraries) | h5plib | /h5p/h5plib | Plugin type for the particular versions of the H5P integration library. | 3.9+ |
+| [Question bank plugins](./qbank/index.md) | qbank | /question/bank | Plugin type for extending question bank functionality. | 4.0+ |
+
+View example
+
+
+import BaseComponents from '!!raw-loader!./_examples/lib_components.php';
+export const BaseComponentsProps = {
+ examplePurpose: 'Format base class with components enabled',
+ plugintype: 'format',
+ pluginname: 'pluginname',
+ filepath: '/lib.php',
+};
+
+
+{getExample(BaseComponentsProps, BaseComponents)}
+
+
+
+
+## Plugin type deprecation
+
+Obtaining the list of plugin types known to your Moodle
+ +You can get an exact list of valid plugin types for your Moodle version using the following example: + +```php title="/plugintypes.php" +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) + ; +} +``` + +
+
+
+Some of the important files for the mlbackend plugintype are described below. See the [common plugin files](../commonfiles) documentation for details of other files which may be useful in your plugin.
+
+## Interfaces
+
+A summary of these interfaces purpose:
+
+- Evaluate a provided prediction model
+- Train machine learning algorithms with the existing site data
+- Predict targets based on previously trained algorithms
+
+### Predictor
+
+This is the basic interface to be implemented by machine learning backends. Two main types are, *classifiers* and *regressors*. We provide the *Regressor* interface but it is not currently implemented by core Machine learning backends. Both of these are supervised algorithms. Each type includes methods to train, predict and evaluate datasets.
+
+You can use **is_ready** to check that the backend is available.
+
+```php
+/**
+ * Is it ready to predict?
+ *
+ * @return bool
+ */
+public function is_ready();
+```
+
+**clear_model** and **delete_output_dir** purpose is to clean up stuff created by the machine learning backend.
+
+```php
+/**
+ * Delete all stored information of the current model id.
+ *
+ * This method is called when there are important changes to a model,
+ * all previous training algorithms using that version of the model
+ * should be deleted.
+ *
+ * @param string $uniqueid The site model unique id string
+ * @param string $modelversionoutputdir The output dir of this model version
+ * @return null
+ */
+public function clear_model($uniqueid, $modelversionoutputdir);
+
+/**
+ * Delete the output directory.
+ *
+ * This method is called when a model is completely deleted.
+ *
+ * @param string $modeloutputdir The model directory id (parent of all model versions subdirectories).
+ * @param string $uniqueid The site model unique id string
+ * @return null
+ */
+public function delete_output_dir($modeloutputdir, $uniqueid);
+```
+
+### Classifier
+
+A [classifier](https://en.wikipedia.org/wiki/Statistical_classification) sorts input into two or more categories, based on analysis of the indicators. This is frequently used in binary predictions, e.g. course completion vs. dropout. This machine learning algorithm is "supervised": It requires a training data set of elements whose classification is known (e.g. courses in the past with a clear definition of whether the student has dropped out or not). This is an interface to be implemented by machine learning backends that support classification. It extends the *Predictor* interface.
+
+Both these methods and *Predictor* methods should be implemented.
+
+```php
+/**
+ * Train this processor classification model using the provided supervised learning dataset.
+ *
+ * @param string $uniqueid
+ * @param \stored_file $dataset
+ * @param string $outputdir
+ * @return \stdClass
+ */
+public function train_classification($uniqueid, \stored_file $dataset, $outputdir);
+
+/**
+ * Classifies the provided dataset samples.
+ *
+ * @param string $uniqueid
+ * @param \stored_file $dataset
+ * @param string $outputdir
+ * @return \stdClass
+ */
+public function classify($uniqueid, \stored_file $dataset, $outputdir);
+
+/**
+ * Evaluates this processor classification model using the provided supervised learning dataset.
+ *
+ * @param string $uniqueid
+ * @param float $maxdeviation
+ * @param int $niterations
+ * @param \stored_file $dataset
+ * @param string $outputdir
+ * @param string $trainedmodeldir
+ * @return \stdClass
+ */
+public function evaluate_classification($uniqueid, $maxdeviation, $niterations, \stored_file $dataset, $outputdir);
+```
+
+### Regressor
+
+A [regressor](https://en.wikipedia.org/wiki/Regression_analysis) predicts the value of an outcome (or dependent) variable based on analysis of the indicators. This value is linear, such as a final grade in a course or the likelihood a student is to pass a course. This machine learning algorithm is "supervised": It requires a training data set of elements whose classification is known (e.g. courses in the past with a clear definition of whether the student has dropped out or not). This is an interface to be implemented by machine learning backends that support regression. It extends *Predictor* interface.
+
+Both these methods and *Predictor* methods should be implemented.
+
+```php
+/**
+ * Train this processor regression model using the provided supervised learning dataset.
+ *
+ * @param string $uniqueid
+ * @param \stored_file $dataset
+ * @param string $outputdir
+ * @return \stdClass
+ */
+public function train_regression($uniqueid, \stored_file $dataset, $outputdir);
+
+/**
+ * Estimates linear values for the provided dataset samples.
+ *
+ * @param string $uniqueid
+ * @param \stored_file $dataset
+ * @param mixed $outputdir
+ * @return void
+ */
+public function estimate($uniqueid, \stored_file $dataset, $outputdir);
+
+
+/**
+ * Evaluates this processor regression model using the provided supervised learning dataset.
+ *
+ * @param string $uniqueid
+ * @param float $maxdeviation
+ * @param int $niterations
+ * @param \stored_file $dataset
+ * @param string $outputdir
+ * @param string $trainedmodeldir
+ * @return \stdClass
+ */
+public function evaluate_regression($uniqueid, $maxdeviation, $niterations, \stored_file $dataset, $outputdir);
+```
diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod/_activitymodule/activity-chooser-info.png b/versioned_docs/version-5.1/apis/plugintypes/mod/_activitymodule/activity-chooser-info.png
new file mode 100644
index 0000000000..2d2b39bc1a
Binary files /dev/null and b/versioned_docs/version-5.1/apis/plugintypes/mod/_activitymodule/activity-chooser-info.png differ
diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod/_activitymodule/activity-chooser-recommend.png b/versioned_docs/version-5.1/apis/plugintypes/mod/_activitymodule/activity-chooser-recommend.png
new file mode 100644
index 0000000000..0b6147facc
Binary files /dev/null and b/versioned_docs/version-5.1/apis/plugintypes/mod/_activitymodule/activity-chooser-recommend.png differ
diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod/_activitymodule/activity-chooser-starred.png b/versioned_docs/version-5.1/apis/plugintypes/mod/_activitymodule/activity-chooser-starred.png
new file mode 100644
index 0000000000..b3aeb20f1d
Binary files /dev/null and b/versioned_docs/version-5.1/apis/plugintypes/mod/_activitymodule/activity-chooser-starred.png differ
diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod/_files/access_description.md b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/access_description.md
new file mode 100644
index 0000000000..7fc9b95250
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/access_description.md
@@ -0,0 +1,20 @@
+
+For activities the following capabilities are _required_:
+
+- `mod/[modname]:addinstance`: Controls whether a user may create a new instance of the activity
+- `mod/[modname]:view`: Controls whether a user may view an instance of the activity
+
+The example below shows the recommended configuration for the `addinstance` and `view` capabilities.
+
+This configuration will allow:
+
+- editing teachers and managers to create new instances, but not non-editing teachers.
+- all roles to view the activity.
+
+:::important
+
+Granting the view capability to archetypes like `guest` does not allow any user to view all activities. Users are still subject to standard access controls like course enrolment.
+
+:::
+
+For further information on what each attribute in that capabilities array means visit [NEWMODULE Adding capabilities](https://docs.moodle.org/dev/NEWMODULE_Adding_capabilities).
diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod/_files/index-php.mdx b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/index-php.mdx
new file mode 100644
index 0000000000..b65d23bcb1
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/index-php.mdx
@@ -0,0 +1,4 @@
+
+The `index.php` should be used to list all instances of an activity that the current user has access to in the specified course.
+
+The [`activityoverviewbase`](../courseoverview.md) class provides a static method to redirect the `mod/PLUGINNAME/index.php` page to the **Activities** page. This method should be called in the `index.php` file of the activity plugin.
diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod/_files/index-php.tsx b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/index-php.tsx
new file mode 100644
index 0000000000..16c5a87463
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/index-php.tsx
@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) Moodle Pty Ltd.
+ *
+ * Moodle is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Moodle is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Moodle. If not, see View an example directory layout for the `mlbackend_python` plugin.
+ +```console +lib/mlbackend/python +├── classes +│ ├── privacy +│ │ └── provider.php +│ └── processor.php +├── lang +│ └── en +│ └── mlbackend_python.php +├── phpunit.xml +├── settings.php +├── tests +│ └── processor_test.php +├── upgrade.txt +└── version.php +``` + +
+
+
+:::tip
+
+To have your Activity plugin classified in the right Activity category, you must define the function `[modname]_supports` and add the `FEATURE_MOD_PURPOSE` constant:
+
+View example
+
+
+```php
+function [modname]_supports($feature) {
+ return match ($feature) {
+ FEATURE_GROUPS => true,
+ FEATURE_GROUPINGS => true,
+ FEATURE_MOD_INTRO => true,
+ FEATURE_COMPLETION_TRACKS_VIEWS => true,
+ FEATURE_GRADE_HAS_GRADE => true,
+ FEATURE_BACKUP_MOODLE2 => true,
+ FEATURE_SHOW_DESCRIPTION => true,
+ FEATURE_MOD_PURPOSE => MOD_PURPOSE_COLLABORATION,
+ default => null,
+ };
+}
+```
+
+
+
+
+
+The available activity purposes for this feature are:
+
+- **Administration** (`MOD_PURPOSE_ADMINISTRATION`) View example
+
+
+```php
+function [modname]_supports(string $feature) {
+ switch ($feature) {
+ [...]
+ case FEATURE_MOD_PURPOSE:
+ return MOD_PURPOSE_XXXXXX;
+
+ default:
+ return null;
+ }
+}
+```
+
+
++Tools for course administration, such as attendance tracking or appointment scheduling. +- **Assessment** (`MOD_PURPOSE_ASSESSMENT`)
+Activities that allow the evaluation and measurement of student understanding and performance.
+ - Core activities in this category: Assignment, Quiz, Workshop. +- **Collaboration** (`MOD_PURPOSE_COLLABORATION`)
+Tools for collaborative learning that encourage knowledge sharing, discussions, and teamwork.
+ - Core activities in this category: Database, Forum, Glossary, Wiki. +- **Communication** (`MOD_PURPOSE_COMMUNICATION`)
+Activities that facilitate real-time communication, asynchronous interaction, and feedback collection.
+ - Core activities in this category: BigBlueButton, Chat, Choice, Feedback, Survey. +- **Interactive content** (`MOD_PURPOSE_INTERACTIVECONTENT`)
+Engaging interactive activities that encourage active learner participation.
+ - Core activities in this category: H5P, IMS package, Lesson, SCORM package. +- **Resources** (`MOD_PURPOSE_CONTENT`)
+Activities and tools to organise and display course materials like documents, web links, and multimedia.
+ - Core activities in this category: Book, File, Folder, Page, URL, Text and media area. +- **Other** (`MOD_PURPOSE_OTHER`)
+Other types of activities. + +::: diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.mdx b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.mdx new file mode 100644 index 0000000000..95055149e0 --- /dev/null +++ b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.mdx @@ -0,0 +1,16 @@ + +This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called `mod_[modname]_mod_form`. + +:::warning + +The `mod_[modname]_mod_form` is a current exception to the class autoloading rules. + +This will be addressed in [MDL-74472](https://moodle.atlassian.net/browse/MDL-74472). + +::: + +:::info + +The following example gives a sample implementation of the creation form. It does **not** contain the full file. + +::: diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.tsx b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.tsx new file mode 100644 index 0000000000..71c4745642 --- /dev/null +++ b/versioned_docs/version-5.1/apis/plugintypes/mod/_files/mod_form-php.tsx @@ -0,0 +1,106 @@ +/** + * Copyright (c) Moodle Pty Ltd. + * + * Moodle is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * Moodle is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with Moodle. If not, see
+
+
+## Standard Files and their Functions
+
+There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into Moodle. Each file has a particular function, some of the files are optional, and are only created if you want to use the functionality it offers. Below are the list of most commonly used files.
+
+### Backup Folder
+
+View an example directory layout for the `folder` plugin.
+
+
+```console
+.
+├── backup
+│ ├── moodle1
+│ │ └── lib.php
+│ └── moodle2
+│ ├── backup_folder_activity_task.class.php
+│ ├── backup_folder_stepslib.php
+│ ├── restore_folder_activity_task.class.php
+│ └── restore_folder_stepslib.php
+├── classes
+│ ├── analytics
+│ │ └── indicator
+│ │ ├── activity_base.php
+│ │ ├── cognitive_depth.php
+│ │ └── social_breadth.php
+│ ├── content
+│ │ └── exporter.php
+│ ├── event
+│ │ ├── all_files_downloaded.php
+│ │ ├── course_module_instance_list_viewed.php
+│ │ ├── course_module_viewed.php
+│ │ └── folder_updated.php
+│ ├── external.php
+│ ├── privacy
+│ │ └── provider.php
+│ └── search
+│ └── activity.php
+├── db
+│ ├── access.php
+│ ├── install.php
+│ ├── install.xml
+│ ├── log.php
+│ ├── services.php
+│ └── upgrade.php
+├── download_folder.php
+├── edit.php
+├── edit_form.php
+├── index.php
+├── lang
+│ └── en
+│ └── folder.php
+├── lib.php
+├── locallib.php
+├── mod_form.php
+├── module.js
+├── phpunit.xml
+├── pix
+│ ├── icon.png
+│ └── icon.svg
+├── readme.txt
+├── renderer.php
+├── settings.php
+├── styles.css
+├── tests
+│ ├── backup
+│ │ └── restore_date_test.php
+│ ├── behat
+│ │ └── folder_activity_completion.feature
+│ ├── event
+│ │ └── events_test.php
+│ ├── externallib_test.php
+│ ├── generator
+│ │ └── lib.php
+│ ├── generator_test.php
+│ ├── lib_test.php
+│ ├── phpunit.xml
+│ └── search
+│ └── search_test.php
+├── version.php
+└── view.php
+```
+
+
+This will display below the module.
'; + return $info; +} +``` + +You can change several properties which are documented in that class definition. If you don't change a property, its value remains default. + +- `name` - name of activity (text of the link on course page). +- `icon`, `iconcomponent` - name and component name of icon to display by the link. +- `content` - extra HTML content to display below the module link on course page (not shown in navigation etc). +- `customdata` - arbitrary extra PHP data to store in modinfo cache; useful if, for performance reasons, your module needs to store data that should be accessible very quickly from other parts of the course. Warning: Do not store complex objects here because when they are serialized (together with all other data) they may contain \0 byte and it causes fatal error on Postgres. +- `extraclasses` - extra CSS class or classes that will be added to the activity on the main page, so that you can alter the styling. +- `onclick` - already-escaped HTML that will be inserted as the value of the onclick attribute. + +If you don't need the information to be cached (it can be retrieved very quickly without making any database queries) then you might consider using one of the functions below instead, in order to avoid unnecessarily increasing the size of the course cache. Although the headings mention the current user, you can of course use those functions in a way that doesn't depend on the current user. + +Don't use renderers in this function (see MDL-41074). If you have data you would like to render onto the course page, put it into the custom data property and render it in the MODNAME_cm_info_view() function (see below). For an example, see mod_folder. + +## Customising module display, for current user + +You can customise module display dynamically (when the page loads). For example you might want to alter it based on the permissions of the current user. + +```php +function mod_frog_cm_info_dynamic(cm_info $cm) { + $context = get_context_instance(CONTEXT_MODULE, $cm->id); + if (!has_capability('some/capability', $context)) { + $cm->set_user_visible(false); + } +} +``` + +This code can affect the navigation, and whether users are permitted to access the module (as above). It runs on all pages within the course, so it's very important that you do not put slow code in this function: it should not make any database queries. + +In addition to the `set_user_visible` function shown, you can also set many other things such as additional editing icons which will appear if editing mode is enabled. See the cm_info class documentation for more information. + +Most things are set using functions (as above; another example would be `set_content` which sets the same content data as mentioned in the previous section) while other things can be set directly using public variables. + +## Customising module display, for current user, on course page only + +Sometimes you need to display custom information for the current user that appears only on the course view page. For example, the forum module displays unread information on the view page. This information doesn't show on other pages (it isn't included in the navigation, for instance). + +```php +function mod_frog_cm_info_view(cm_info $cm) { + $cm->set_after_link('Last tadpole: 22:17'); +} +``` + +Because this function only runs when looking at the course page: + +- It is OK to do tasks which may require some database queries (such as checking for unread forum messages), although obviously this should be kept to a minimum. In particular, care should be taken so that if there are 20 instances of the activity on the course page, it doesn't make 20 separate queries to obtain the information. + +- Inside this function you cannot set options which affect the appearance or access to the activity on other pages; for example, you cannot turn off the `uservisible` flag as shown in the previous example. This is because these options are required on other pages (e.g. to display navigation) so it does not make sense to set them only for the course page. If you try, you'll get a `coding_exception`. + +## get_fast_modinfo data + +The function `get_fast_modinfo` now returns an object of class course_modinfo, which itself contains cm_info objects about each activity. (These are entirely backward-compatible with the previous return value.) + +In addition to the old methods for obtaining data from $modinfo, there are some new functions. For example, here is how to get a single cm_info from $modinfo: + +```php +$modinfo = get_fast_modinfo($course); +$cm = $modinfo->get_cm($cmid); +``` + +The cm_info objects contain additional information that is not present in the course_modules database row, such as the module's name, and the icon and associated content mentioned above. In order to distinguish these from the plain database objects, you can specify the cm_info class in a function definition: + +```php +function my_clever_function(cm_info $cm) { + if (!$cm->uservisible) { + // The module is not visible or available to current user, + // so do something clever instead. + } +} +``` + +By specifying cm_info in the parameter list, you'll cause PHP to give an error if anyone tries to call that function with a $cm object that just came from the database row, instead of from `get_fast_modinfo`. (It is good practice to always get $cm from get_fast_modinfo, but there might be exceptions.) + +Of course, this is only necessary if your function relies on a feature that is specific to cm_info, such as the `uservisible` field above. If your function only uses fields which are present in the database row, then there's no need to require cm_info. + +## More documentation + +All three classes for this API are in the core file `lib/modinfolib.php` and contain complete PHPdoc information for all fields and functions. + +- [`course_modinfo` PHPdocs](http://phpdocs.moodle.org/HEAD/core/lib/course_modinfo.html) +- [`cminfo` PHPdocs](http://phpdocs.moodle.org/HEAD/core/lib/cm_info.html) +- [`cached_cm_info` PHPdocs](http://phpdocs.moodle.org/HEAD/core/lib/cached_cm_info.html) diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod_book/index.md b/versioned_docs/version-5.1/apis/plugintypes/mod_book/index.md new file mode 100644 index 0000000000..a28f112e96 --- /dev/null +++ b/versioned_docs/version-5.1/apis/plugintypes/mod_book/index.md @@ -0,0 +1,10 @@ +--- +title: Book activity sub-plugins +tags: + - Book + - Subplugin + - Plugintype +documentationDraft: true +--- + +The `mod_book` activity can be extended using the tool sub-plugin type. This hasn't been documented yet - perhaps you are able to help us. diff --git a/versioned_docs/version-5.1/apis/plugintypes/mod_data/fields.md b/versioned_docs/version-5.1/apis/plugintypes/mod_data/fields.md new file mode 100644 index 0000000000..3d1bf3e009 --- /dev/null +++ b/versioned_docs/version-5.1/apis/plugintypes/mod_data/fields.md @@ -0,0 +1,81 @@ +--- +title: Database fields +tags: + - mod_data + - datafield + - plugintype + - subplugin +documentationDraft: true +--- + +The [Database activity](https://docs.moodle.org/en/Database_module) included with Moodle includes support for several predefined [field types](./fields.md), including text, date, and URL. It is also possible to create new field types. For example, you might like to create: + +- Discipline-specific field types - For example "Protein PDB code": users can enter the PDB code for a protein, and then the display 3D viewer for the protein structure, or link out to molecular databases. +- Institution-specific field types - For example "library reference number": Allow users to enter a reference number which can be automatically turned into a direct link for local library services. +- Module-specific field types - For example "wiki page": users see a drop-down list containing the names of pages in your wiki, and can choose which page this particular entry refers to. + +import { ComponentFileSummary } from '../../../_utils'; + +## File structure + +Database field sub-plugins are located in the `/mod/data/field` directory. + +Each plugin is in a separate subdirectory and consists of a number of _mandatory files_ and any other files the developer is going to use. + +
+
+
+Some of the important files for the database field plugintype are described below. See the [common plugin files](../../commonfiles/index.mdx) documentation for details of other files which may be useful in your plugin.
+
+### Field class
+
+View an example directory layout for the `datafield_number` subplugin.
+ +```console +mod/data/field/number +├── classes +│ └── privacy +│ └── provider.php +├── field.class.php +├── lang +│ └── en +│ └── datafield_number.php +├── mod.html +└── version.php +``` + +
+
+
+Some of the important files for the format plugintype are described below. See the [common plugin files](../commonfiles) documentation for details of other files which may be useful in your plugin.
+
+### rule.php
+
+import RuleFile from '!!raw-loader!./_examples/rule.php';
+import RuleDescription from './_examples/rule.md';
+
+View an example directory layout for the `quizaccess_delaybetweenattempts` plugin.
+ +```console +mod/quiz/accessrule/delaybetweenattempts +├── classes +│ └── privacy +│ └── provider.php +├── lang +│ └── en +│ └── quizaccess_delaybetweenattempts.php +├── tests +│ └── rule_test.php +├── rule.php +└── version.php +``` + +
+
+
+Some of the important files for the repository plugintype are described below. See the [common plugin files](../commonfiles) documentation for details of other files which may be useful in your plugin.
+
+### version.php
+
+View an example directory layout for the `repository_pluginname` plugin.
+ +```console + repository/pluginname/ + |-- db + | `-- access.php + |-- lang + | `-- en + | `-- repository_pluginname.php + |-- lib.php + |-- pix + | `-- icon.png + `-- version.php +``` + +
+
+
+#### type_config_form($mform, $classname='repository')
+
+This function must be declared static
+
+Optional. This is for modifying the Moodle form displaying the plugin settings. The [Form Definition](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition) documentation has details of all the types of elements you can add to the settings form.
+
+View example
+
+
+```php
+public static function get_type_option_names() {
+ return array_merge(parent::get_type_option_names(), ['rootpath']);
+}
+```
+
+
+
+
+
+#### type_form_validation($mform, $data, $errors)
+
+This function must be declared static
+
+Optional. Use this function if you need to validate some variables submitted by plugin settings form. To use it, check through the associative array of data provided ('settingname' => value) for any errors. Then push the items to $error array in the format ("fieldname" => "human readable error message") to have them highlighted in the form.
+
+```php
+public static function type_form_validation($mform, $data, $errors) {
+ if (!is_dir($data['rootpath'])) {
+ $errors['rootpath'] = get_string('invalidrootpath', 'repository_pluginname');
+ }
+ return $errors;
+}
+```
+
+### Instance settings
+
+These functions relate to a specific instance of your plugin (for example the URL and login details to access a specific webdav repository). All of these are optional, without them, the instance settings form will only contain a single 'name' field.
+
+#### get_instance_option_names(): array
+
+This function must be declared static
+
+Optional. Return an array of strings. These strings are setting names. These settings are specific to an instance.
+
+If the function returns an empty array, the API will consider that the plugin displays only one repository in the file picker.
+
+Parent function returns an empty array. This is equivalent to **get_type_option_names()**, but for a specific instance.
+
+View example
+
+
+For example, to display the standard repository plugin settings along with the custom ones use:
+
+```php
+public static function type_config_form($mform, $classname='repository') {
+ parent::type_config_form($mform);
+
+ $rootpath = get_config('repository_pluginname', 'rootpath');
+ $mform->addElement('text', 'rootpath', get_string('rootpath', 'repository_pluginname'), array('size' => '40'));
+ $mform->setDefault('rootpath', $rootpath);
+}
+```
+
+
+
+
+
+#### instance_config_form($mform)
+
+This function must be declared static
+
+Optional. This is for modifying the Moodle form displaying the settings specific to an instance. This is equivalent to **type_config_form($mform, $classname)** but for instances. The [Form Definition](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition) documentation has details of all the types of elements you can add to the settings form.
+
+View example
+
+
+```php
+public static function get_instance_option_names() {
+ return ['fs_path']; // From repository_filesystem
+}
+```
+
+
+
+
+
+:::note
+
+**mform** has by default a name text box (cannot be removed).
+
+:::
+
+#### instance_form_validation($mform, $data, $errors)
+
+This function must be declared static
+
+Optional. This allows us to validate what has been submitted in the instance configuration form. This is equivalent to ''type_form_validation($mform, $data, $errors), but for instances. For example:
+
+```php
+public static function instance_form_validation($mform, $data, $errors) {
+ if (empty($data['email_address'])) {
+ $errors['email_address'] = get_string('invalidemailsettingname', 'repository_flickr_public');
+ }
+}
+```
+
+#### Getting / updating settings
+
+Both global and instance settings can be retrieved, from within the plugin, via **$this->get_option('settingname')** and updated via **$this->set_option(array('settingname' => 'value'))**.
+
+:::note
+
+You cannot call **$this** from static methods. If you need access the non static variables, you may have to store the values in the **_construct()** method into private static variables.
+
+:::
+
+#### plugin_init()
+
+This function must be declared static.
+
+Optional. This function is called when the administrator adds the plugin. So unless the administrator deletes the plugin and re-adds it, it should be called only once.
+
+Parent function does nothing.
+
+### Example of using the settings
+
+As an example, let's create a Flickr plugin for accessing a public flickr account. The plugin will be called "Flickr Public".
+
+Firstly the skeleton:
+
+```php title="repository/flickr_public/lib.php"
+
+
+import FlickPublicLib from '!!raw-loader!./_examples/flickr_public_lib.php';
+
+View example
+
+
+For example, to add a required text box called email_address:
+
+```php
+public static function get_instance_option_names() {
+ $mform->addElement(
+ 'text',
+ 'email_address',
+ get_string('emailaddress', 'repository_pluginname')
+ );
+ $mform->addRule('email_address', $strrequired, 'required', null, 'client');
+}
+```
+
+
+
+
+
+Amongst other details, this returns a **title** for each file (to be displayed in the filepicker) and the **source** for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a **children** value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.
+
+View example
+
+
+```php
+/**
+ * Get file listing.
+ *
+ * This is a mandatory method for any repository.
+ *
+ * See repository::get_listing() for details.
+ *
+ * @param string $encodedpath
+ * @param string $page
+ * @return array the list of files, including meta information
+ */
+public function get_listing($encodedpath = '', $page = '') {
+ // This methods
+ return [
+ //this will be used to build navigation bar.
+ 'path'=>[
+ [
+ 'name'=>'root'
+ 'path'=>'/'
+ ],
+ [
+ 'name'=>'subfolder',
+ 'path'=>'/subfolder'
+ ],
+ ],
+ 'manage'=>'http://webmgr.moodle.com',
+ 'list'=> [
+ [
+ 'title'=>'filename1',
+ 'date'=>'1340002147',
+ 'size'=>'10451213',
+ 'source'=>'http://www.moodle.com/dl.rar',
+ ],
+ [
+ 'title'=>'folder',
+ 'date'=>'1340002147',
+ 'size'=>'0',
+ 'children'=>[],
+ ],
+ ],
+ ];
+}
+```
+
+
+
+
+
+### Dynamically loading
+
+Some repositories contain many files which cannot load in one time, in this case, we need dynamically loading to fetch them step by step, files in subfolder won't be listed until user click the folder in file picker treeview.
+
+As a plug-in developer, if you set dynload flag as **true**, you should return files and folders (set children as a null array) in current path only instead of building the whole file tree.
+
+The use of the **object** tag, instead of returning a **list** of files, allows you to embed an external file chooser within the repository panel. See [Repository plugins embedding external file chooser](https://docs.moodle.org/dev/Repository_plugins_embedding_external_file_chooser) for details about how to do this.
+
+### User login (optional)
+
+If our plugin allows a user to log in to a remote service, you can support this using the `print_login()` and `check_login` function, which are desribed below.
+
+#### print_login
+
+For plugins which need to support login to a remote service, the `print_login()` function can be used to return an array of the form elements needed to support the login.
+
+The full specification of list element
+
+
+import FullList from '!!raw-loader!./_examples/full_list.jsonc';
+
+{FullList}
+
+
+
+
+
+This will help to generate a form by file picker which contains user name and password input elements.
+
+If your login form is static and never changes, you can add `$ret['allowcaching']) = true;` and filepicker will not send the request to the server every time user opens the login/search form.
+
+For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the `__construct` function, via `$submitted = optional_param('fieldname', [PARAM_INT/PARAM_TEXT)`.
+
+View example
+
+
+:::note
+
+It is important to note that the repository login can be called on both Ajax and non ajax requests. For this reason the `print_login()` should check for `$this->options['ajax']` to know if it should return an array or the full login HTML form.
+
+:::
+
+```php
+public function print_login() { // From repository_pluginname
+ global $OUTPUT;
+
+ if ($this->options['ajax']) {
+ $user_field = (object) [
+ 'label' => get_string('username', 'repository_pluginname'),
+ 'id' => 'pluginname_username',
+ 'type' => 'text',
+ 'name' => 'al_username',
+ ];
+
+ $passwd_field = (object) [
+ 'label' => get_string('password', 'repository_pluginname'),
+ 'id' => 'pluginname_password',
+ 'type' => 'password',
+ 'name' => 'al_password',
+ ];
+
+ $ret = [];
+ $ret['login'] = [$user_field, $passwd_field];
+ return $ret;
+ } else { // Non-AJAX login form - directly output the form elements.
+ // Print the login form HTML including the input username and password fields.
+ $loginform = new repository_pluginname\output\login();
+ echo $OUTPUT->render($loginform);
+ // Example of a login form:
+ //
+ //
+ //
+ //
+ //
+ }
+}
+```
+
+
+
+
+
+Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
+
+View example
+
+
+```php title="lib/alfresco/lib.php"
+public function __construct($repositoryid, $context = SYSCONTEXTID, $options = []) {
+ global $SESSION;
+
+ /* Skipping code that is not relevant to user login */
+
+ $this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
+ $this->username = optional_param('al_username', '', PARAM_RAW);
+ $this->password = optional_param('al_password', '', PARAM_RAW);
+ try{
+ // deal with user logging in.
+ if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
+ $this->ticket = $this->alfresco->authenticate($this->username, $this->password);
+ $SESSION->{$this->sessname} = $this->ticket;
+ } else {
+ if (!empty($SESSION->{$this->sessname})) {
+ $this->ticket = $SESSION->{$this->sessname};
+ }
+ }
+ $this->user_session = $this->alfresco->createSession($this->ticket);
+ $this->store = new SpacesStore($this->user_session);
+ } catch (Exception $e) {
+ $this->logout();
+ }
+ $this->current_node = null;
+
+ /* Skipping code that is not relevant to user login */
+
+}
+```
+
+
+
+
+
+#### check_login(): bool
+
+This function will return a boolean value to tell Moodle whether the user has logged in.
+By default, this function will return true.
+
+```php
+public function check_login(): bool {
+ global $SESSION;
+ return !empty($SESSION->{$this->sessname});
+}
+```
+
+#### logout
+
+When a user clicks the logout button in file picker, this function will be called. You may clean up the session or disconnect the connection with remote server here. After this the code should return something suitable to display to the user (usually the results of calling **$this->print_login()**):
+
+```php title="lib/alfresco/lib.php"
+public function logout() {
+ global $SESSION;
+ unset($SESSION->{$this->sessname});
+ return $this->print_login();
+}
+```
+
+### Transferring files to Moodle (optional)
+
+These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.
+
+#### get_file_reference($source)
+
+This function takes $source as in user input, parses and cleans it (recommended to call clean_param()). It prepares the reference to the file in repository-specific format that would be passed on to methods get_file(), get_link(), get_moodle_file(), get_file_by_reference() and/or stored in DB in case of creating a shortcut to file. For the most of repositories it is just clean $source value. For has_moodle_files-repositories this function also changes encoding.
+
+#### get_file($url, $filename = "")
+
+For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
+
+- path - the local path where the file was saved
+- url - the $url param passed into the function
+
+View example
+
+
+```php title="Code taken from repository_boxnet"
+public function print_login() {
+ $ticket = $this->boxclient->getTicket();
+ if ($this->options['ajax']) {
+ $loginbtn = (object)[
+ 'type' => 'popup',
+ 'url' => ' https://www.box.com/api/1.0/auth/' . $ticket->get_oauth_tokens(),
+ ];
+ $result = [];
+ $result['login'] = [$loginbtn];
+ return $result;
+ } else {
+ // Print the login form HTML including the input username, password and ticket fields.
+ $loginform = new repository_boxnet\output\login($ticket);
+ echo $OUTPUT->render($loginform);
+ // Example of a login form:
+ //
+ //
+ //
+ //
+ //
+ //
+ }
+}
+```
+
+
+
+
+
+#### search($search_text, $page = 0)
+
+Return the results of doing the search. Any additional parameters from the search form can be retrieved by $param = optional_param('paramname', [PARAM_INT / PARAM_TEXT);.
+
+The return should return an array containing:
+
+- list - with the same layout as the 'list' element in 'get_listing'
+
+View example
+
+
+```php title="The default implementation in class 'repository'"
+public function print_search() {
+ global $PAGE;
+ $renderer = $PAGE->get_renderer('core', 'files');
+ return $renderer->repository_default_searchform();
+ // The default search HTML from repository/renderer.php:
+ // ;
+}
+```
+
+
+
+
+
+#### global_search()
+
+Return true if should be included in a search throughout all repositories (currently not available via the UI)
+
+### Repository support for returning file as alias/shortcut
+
+It is possible to link to the file from external (or internal) repository by reference. In UI it is called "create alias/shortcut". This creates a row in `files` table but the contents of the file is not stored. Although it may be cached by repository if developer wants to.
+
+Make sure that function supported_returntypes() returns FILE_REFERENCE among other types.
+
+Note that external file is synchronised by moodle when UI wants to show the file size.
+
+#### get_reference_file_lifetime()
+
+Return minimum number of seconds before checking for changes to the file (default implementation = 1 day)
+
+```php
+public function get_reference_file_lifetime($ref) {
+ return DAYSECS; // One day, 60 * 60 * 24 seconds.
+}
+```
+
+#### sync_individual_file(stored_file $storedfile)
+
+Called after the file has reached the 'lifetime' specified above to see if it should now be synchronised (default implementation is to return true)
+
+```php
+public function sync_individual_file(stored_file $storedfile) {
+ return true;
+}
+```
+
+#### get_reference_details($reference, $filestatus = 0)
+
+Returns human-readable information about where the original file is stored (to be displayed in the filepicker properties box).
+
+This is usually prefixed with the repository name, and a semicolon. For example: `Myrepository: http://url.to.file`.
+
+- `$reference` is the 'source' output by `get_listing`
+- `$filestatus` can be either `0` (OK - default) or `666` (source file missing).
+
+View example
+
+
+```php title="Example from repoistory_googledocs"
+public function search($search_text, $page = 0) {
+ $gdocs = new google_docs($this->googleoauth);
+ return [
+ 'dynload' => true,
+ 'list' => $gdocs->get_file_list($search_text),
+ ];
+}
+```
+
+
+
+
+
+#### get_file_by_reference($reference)
+
+Returns up-to-date information about the original file, only called when the 'lifetime' is reached and 'sync_individual_file' returns true.
+
+- For image files - download the file and return either $ret->filepath (full path on the server), $ret->handle (open handle to the file) or $ret->content (raw data from the file) to allow the file to be saved into the Moodle filesystem and the thumbnail to be updated
+- For non-image files - avoid downloading the file (if possible) and just return $ret->filesize to update that information
+- For missing / inaccessible files - return null
+ Remember this function may be called quite a lot, as the filemanager often wants to know the filesize.
+
+View example
+
+
+```php title="lib.php"
+public function get_reference_details($reference, $filestatus = 0) {
+ if (!$filestatus) {
+ // Replace the line below by any method your plugin have to check a reference.
+ $details = example_external_server::get_details_by_reference($reference);
+ return $this->get_name() . ': ' . $details->filename;
+ } else {
+ return get_string('lostsource', 'repository', '');
+ }
+}
+```
+
+
+
+
+
+#### send_file($storedfile, $lifetime=86400, $filter=0, $forcedownload=false, array $options = null)
+
+Send the requested file back to the user's browser. The 'reference' for the file can be found via $storedfile->get_reference(). If the file is not found / no longer exists, the function 'send_file_not_found()' should be used. Otherwise the file should be output directly, via the most appropriate method:
+
+- Use a 'Location: ' header to redirect to the external URL
+- Download the file and cache within the Moodle filesystem (possibly using '$this->import_external_file_contents()'), then call 'send_stored_file'.
+
+:::note
+
+It is up to the repository developer to decide whether to actually download the file or to return a locally cached copy instead.
+
+:::
+
+View example
+
+
+```php title="/lib.php"
+public function get_file_by_reference($reference) {
+ global $USER;
+ // Replace the line below by any method your plugin have to check a reference.
+ $details = example_external_server::get_details_by_reference($reference->reference));
+ if (!isset($details->url) || !($url = $this->appendtoken($details->url))) {
+ // Occurs when the user isn't known.
+ return null;
+ }
+
+ // Download the file details.
+ $return = null;
+ $cookiepathname = $this->prepare_file($USER->id . '_' . uniqid('', true) . '.cookie');
+ $headparams = ['followlocation' => true, 'timeout' => self::SYNCFILE_TIMEOUT];
+ $curlobject = new curl(['cookie' => $cookiepathname]);
+
+ if (file_extension_in_typegroup($ref->filename, 'web_image')) {
+ // The file is an image - download and return the file path.
+ $path = $this->prepare_file('');
+ $result = $curlobject->download_one($url, null, $headparams);
+ if ($result === true) {
+ $return = (object) ['filepath' => $path];
+ }
+ } else {
+ // The file is not an image - just get the file details.
+
+ $result = $curlobject->head($url, $headparams);
+ }
+
+ // Delete cookie jar.
+ if (file_exists($cookiepathname)) {
+ unlink($cookiepathname);
+ }
+
+ $this->connection_result($ccurlobject->get_errno());
+ $curlinfo = $ccurlobject->get_info();
+ if ($return === null && isset($curlinfo['http_code']('list'])) &&
+ $curlinfo['http_code']== 200 &&
+ array_key_exists('download_content_length', $curlinfo) &&
+ $curlinfo['download_content_length']('http_code']) >= 0) {
+ // We received a correct header and at least can tell the file size.
+ $return = (object) ['filesize' => $curlinfo['download_content_length']];
+ }
+ return $return;
+}
+```
+
+
+
+
+
+An example of caching files within the Moodle filesystem can be found in repository_dropbox.
+
+
diff --git a/versioned_docs/version-5.1/apis/plugintypes/sms/index.md b/versioned_docs/version-5.1/apis/plugintypes/sms/index.md
new file mode 100644
index 0000000000..62869357d4
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/sms/index.md
@@ -0,0 +1,145 @@
+---
+title: SMS gateway
+tags:
+ - SMS
+ - Gateway
+ - Notification
+---
+
+View example
+
+
+```php title="/lib.php"
+public function send_file($stored_file, $lifetime=86400 , $filter=0, $forcedownload=false, array $options = null) {
+ // Replace the line below by any method your plugin have to check a reference.
+ $details = example_external_server::get_details_by_reference($stored_file->get_reference()));
+ $url = $this->appendtoken($details->url);
+ if ($url) {
+ header('Location: ' . $url);
+ } else {
+ send_file_not_found();
+ }
+}
+```
+
+
+
+
+
+## Key files
+
+There are a number of key files within the SMS gateway plugin which will need to be configured for correct functionality.
+
+- `gateway.php`
+- `hook_listener.php`
+
+### gateway.php
+
+Each plugin must create a class called `gateway` which extends the `\core_sms\gateway` class.
+The SMS API will use the extended methods from this class.
+
+```php title="Implementing the base SMS gateway"
+get_gateway_service($config);
+ $recipientnumber = manager::format_number(
+ phonenumber: $message->recipientnumber,
+ countrycode: isset($config->countrycode) ?? null,
+ );
+
+ $status = call_user_func(
+ [$class, 'send_sms_message'],
+ $message->content,
+ $recipientnumber,
+ $config,
+ );
+
+ return $message->with(
+ status: $status,
+ );
+ }
+
+ private function get_gateway_service(\stdClass $config): string {
+ return match ($config->gateway) {
+ 'aws_sns' => aws_sns::class,
+ default => throw new moodle_exception("Unknown Message Handler {$config->gateway}"),
+ };
+ }
+
+ #[\Override]
+ public function get_send_priority(message $message): int {
+ return 50;
+ }
+}
+
+```
+
+### hook_listener.php
+
+[Hooks](/apis/core/hooks/index.md) can be dispatched from the SMS API which the plugin can then listened to.
+It is necessary for plugins developers to assess these hooks and implement accordingly.
+
+#### after_sms_gateway_form_hook
+
+This hook will allow plugins to add required form fields to assist users in configuring their SMS gateway.
+
+```php title="Listener method for after_sms_gateway_form_hook"
+public static function set_form_definition_for_aws_sms_gateway(after_sms_gateway_form_hook $hook): void {
+ if ($hook->plugin !== 'smsgateway_example') {
+ return;
+ }
+
+ $gateways = [
+ 'smsgateway_example' => get_string('list', 'smsgateway_example'),
+ ];
+ $mform->addElement(
+ 'select',
+ 'gateway',
+ get_string('gateway', 'smsgateway_example'),
+ $gateways,
+ );
+}
+
+```
+
+:::info
+
+For an example of a production plugin example, see the [AWS SMS Gateway plugin](https://github.com/moodle/moodle/tree/main/sms/gateway/aws).
+
+:::
diff --git a/versioned_docs/version-5.1/apis/plugintypes/theme/_examples/lang.md b/versioned_docs/version-5.1/apis/plugintypes/theme/_examples/lang.md
new file mode 100644
index 0000000000..09094b1709
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/theme/_examples/lang.md
@@ -0,0 +1,15 @@
+
+
+
+Each plugin must define a set of language strings with, at a minimum, an English translation. These are specified in the plugin's lang/en directory in a file named after the plugin.
+
+Language strings for the plugin. Required strings:
+
+- **`pluginname`** - name of plugin.
+- **`choosereadme`** - descriptive text displayed beneath the theme information dialog screenshot.
+- **`configtitle`** - settings text for this type of plugin.
+
+You will usually need to add your own strings for two main purposes:
+
+- Creating suitable form controls for users who are editing the theme settings; and
+- Displaying information about the theme.
diff --git a/versioned_docs/version-5.1/apis/plugintypes/theme/_examples/lang.php b/versioned_docs/version-5.1/apis/plugintypes/theme/_examples/lang.php
new file mode 100644
index 0000000000..054a1e8c03
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/theme/_examples/lang.php
@@ -0,0 +1,3 @@
+$string['pluginname'] = 'Boost';
+$string['choosereadme'] = 'Boost is a modern, highly-customisable theme. This theme is intended to be used directly, or as a parent theme when creating new themes utilising Bootstrap 4.';
+$string['configtitle'] = 'Boost';
diff --git a/versioned_docs/version-5.1/apis/plugintypes/theme/fonts.md b/versioned_docs/version-5.1/apis/plugintypes/theme/fonts.md
new file mode 100644
index 0000000000..c60955d011
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/theme/fonts.md
@@ -0,0 +1,77 @@
+---
+title: Fonts
+tags:
+ - Plugins
+ - Theme
+ - Fonts
+sidebar_position: 3
+---
+
+The directory layout for the `smsgateway` plugin.
+ +```console +sms/gateway/example +├── classes +│ ├── gateway.php +│ ├── hook_listener.php +│ └── privacy +│ └── provider.php +├── db +│ └── hooks.php +├── lang +│ └── en +│ └── smsgateway_example.php +├── settings.php +└── version.php +``` + +
+
+
+Some of the important files for the Theme plugintype are described below. See the [common plugin files](../commonfiles) documentation for details of other files which may be useful in your plugin.
+
+:::tip Override icons and templates
+
+You can customize icons in base themes:
+
+1. Without altering core code by placing them in `$CFG->dataroot/pix` and `$CFG->dataroot/pix_plugins`. If a theme extends a base theme and includes its own icons, those will take precedence.
+1. Adding custom icons to a theme by placing them in the theme's `pix_core` and `pix_plugins` directories, as described in the [Override images section](./theme/images#override-images).
+
+:::
+
+Similarly, mustache templates in base themes can be overridden without impacting core code by placing them in `templates/[componentname]/[templatename].mustache`.
+
+### config.php
+
+All theme options are set within the `config.php` file for the theme.
+
+View an example directory layout for a `theme_example` plugin.
+ +```console + theme/example + |-- amd + | └-- src + |-- classes + | └-- output + |-- fonts + |-- fonts_core + |-- fonts_plugins + | └-- plugintype + | └-- pluginname + |-- lang + | └-- en + | └-- theme_example.php + |-- layout + |-- pix + | └-- favicon.ico + | └-- screenshot.png + |-- pix_plugins + | └-- plugintype + | └-- pluginname + |-- style + |-- scss + |-- templates + |-- config.php + |-- settings.php + └-- version.php +``` + +
+
+
+Everything is added to `$THEME`. This is the theme's configuration object, it is created by Moodle using default settings and is then updated by whatever settings are added to it.
+
+- `$THEME->name`. The theme's name should simply be whatever the theme's name is, most likely whatever the theme directory is named.
+- `$THEME->sheets`. An array containing the names of the CSS stylesheets to include for this theme. Boost uses SCSS instead of CSS so it doesn't list any files here.
+
+:::note
+
+It is just the name of the stylesheet and does not contain the directory or the file extension. Moodle assumes that the theme's stylesheets will be located in the `{theme}/style` directory of the theme and have .css as an extension.
+
+:::
+
+- `$THEME->editorsheets`. An array containing the names of the CSS stylesheets to include for text editor content area. Boost does not list any stylesheets here so text editors will use plain text styles.
+- `$THEME->layouts`. Any of the different layout types can be mapped. For more information see the [layouts section](./theme/layout).
+- `$THEME->parents`. Defines the themes that the theme will extend. Boost has no parents, but if a theme is extending boost, it should be listed it here like:
+
+```php
+$THEME->parents = ['boost'];
+```
+
+- `$THEME->enable_dock`. Boost does not support docking blocks.
+- `$THEME->csstreepostprocessor`. Boost uses a function to post process the CSS. This is an advanced feature and is used in boost to automatically apply vendor prefixes to CSS styles.
+- `$THEME->rendererfactory`. Almost all themes need this setting to be set to `theme_overridden_renderer_factory` or the theme will not be able to customise any core renderers.
+- `$THEME->undeletableblocktypes`. This is a comma separated list of block types that cannot be deleted in this theme. If you don't define this, the admin and settings blocks will be undeletable by default. Because Boost provides alternate ways to navigate it does not require any blocks.
+
+:::tip
+
+When you first begin writing themes, make sure you take a look at the configuration files of the other themes that get shipped with Moodle. You will get a good picture of how everything works, and what is going on in a theme, simply by reading it and taking notice of what it is including or excluding.
+
+:::
+
+Have a look at the following theme options for a complete list of theme options which include lesser used specialised or advanced settings:
+
+View basic theme config.php
+
+
+```php
+.
+
+/**
+ * Boost config.
+ *
+ * @package theme_boost
+ * @copyright 2016 Frédéric Massart
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+require_once(__DIR__ . '/lib.php');
+
+$THEME->name = 'boost';
+$THEME->sheets = [];
+$THEME->editor_sheets = [];
+$THEME->editor_scss = ['editor'];
+$THEME->usefallback = true;
+$THEME->scss = function($theme) {
+ return theme_boost_get_main_scss_content($theme);
+};
+
+$THEME->layouts = [
+ // Most backwards compatible layout without the blocks.
+ 'base' => array(
+ 'file' => 'drawers.php',
+ 'regions' => array(),
+ ),
+ // Standard layout with blocks.
+ 'standard' => array(
+ 'file' => 'drawers.php',
+ 'regions' => array('side-pre'),
+ 'defaultregion' => 'side-pre',
+ ),
+ // Main course page.
+ 'course' => array(
+ 'file' => 'drawers.php',
+ 'regions' => array('side-pre'),
+ 'defaultregion' => 'side-pre',
+ 'options' => array('langmenu' => true),
+ ),
+ 'coursecategory' => array(
+ 'file' => 'drawers.php',
+ 'regions' => array('side-pre'),
+ 'defaultregion' => 'side-pre',
+ ),
+ // Part of course, typical for modules - default page layout if $cm specified in require_login().
+ 'incourse' => array(
+ 'file' => 'drawers.php',
+ 'regions' => array('side-pre'),
+ 'defaultregion' => 'side-pre',
+ ),
+ // The site home page.
+ 'frontpage' => array(
+ 'file' => 'drawers.php',
+ 'regions' => array('side-pre'),
+ 'defaultregion' => 'side-pre',
+ 'options' => array('nonavbar' => true),
+ ),
+ // Server administration scripts.
+ 'admin' => array(
+ 'file' => 'drawers.php',
+ 'regions' => array('side-pre'),
+ 'defaultregion' => 'side-pre',
+ ),
+ // My courses page.
+ 'mycourses' => array(
+ 'file' => 'drawers.php',
+ 'regions' => ['side-pre'],
+ 'defaultregion' => 'side-pre',
+ 'options' => array('nonavbar' => true),
+ ),
+ // My dashboard page.
+ 'mydashboard' => array(
+ 'file' => 'drawers.php',
+ 'regions' => array('side-pre'),
+ 'defaultregion' => 'side-pre',
+ 'options' => array('nonavbar' => true, 'langmenu' => true),
+ ),
+ // My public page.
+ 'mypublic' => array(
+ 'file' => 'drawers.php',
+ 'regions' => array('side-pre'),
+ 'defaultregion' => 'side-pre',
+ ),
+ 'login' => array(
+ 'file' => 'login.php',
+ 'regions' => array(),
+ 'options' => array('langmenu' => true),
+ ),
+
+ // Pages that appear in pop-up windows - no navigation, no blocks, no header and bare activity header.
+ 'popup' => array(
+ 'file' => 'columns1.php',
+ 'regions' => array(),
+ 'options' => array(
+ 'nofooter' => true,
+ 'nonavbar' => true,
+ 'activityheader' => [
+ 'notitle' => true,
+ 'nocompletion' => true,
+ 'nodescription' => true
+ ]
+ )
+ ),
+ // No blocks and minimal footer - used for legacy frame layouts only!
+ 'frametop' => array(
+ 'file' => 'columns1.php',
+ 'regions' => array(),
+ 'options' => array(
+ 'nofooter' => true,
+ 'nocoursefooter' => true,
+ 'activityheader' => [
+ 'nocompletion' => true
+ ]
+ ),
+ ),
+ // Embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible.
+ 'embedded' => array(
+ 'file' => 'embedded.php',
+ 'regions' => array('side-pre'),
+ 'defaultregion' => 'side-pre',
+ ),
+ // Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
+ // This must not have any blocks, links, or API calls that would lead to database or cache interaction.
+ // Please be extremely careful if you are modifying this layout.
+ 'maintenance' => array(
+ 'file' => 'maintenance.php',
+ 'regions' => array(),
+ ),
+ // Should display the content and basic headers only.
+ 'print' => array(
+ 'file' => 'columns1.php',
+ 'regions' => array(),
+ 'options' => array('nofooter' => true, 'nonavbar' => false, 'noactivityheader' => true),
+ ),
+ // The pagelayout used when a redirection is occuring.
+ 'redirect' => array(
+ 'file' => 'embedded.php',
+ 'regions' => array(),
+ ),
+ // The pagelayout used for reports.
+ 'report' => array(
+ 'file' => 'drawers.php',
+ 'regions' => array('side-pre'),
+ 'defaultregion' => 'side-pre',
+ ),
+ // The pagelayout used for safebrowser and securewindow.
+ 'secure' => array(
+ 'file' => 'secure.php',
+ 'regions' => array('side-pre'),
+ 'defaultregion' => 'side-pre'
+ )
+];
+
+$THEME->parents = [];
+$THEME->enable_dock = false;
+$THEME->extrascsscallback = 'theme_boost_get_extra_scss';
+$THEME->prescsscallback = 'theme_boost_get_pre_scss';
+$THEME->precompiledcsscallback = 'theme_boost_get_precompiled_css';
+$THEME->yuicssmodules = [];
+$THEME->rendererfactory = 'theme_overridden_renderer_factory';
+$THEME->requiredblocks = '';
+$THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;
+$THEME->iconsystem = \core\output\icon_system::FONTAWESOME;
+$THEME->haseditswitch = true;
+$THEME->usescourseindex = true;
+// By default, all boost theme do not need their titles displayed.
+$THEME->activityheaderconfig = [
+ 'notitle' => true
+];
+```
+
+
+
+
+
+
+
+### lang/en/themename.php
+
+import langExample from '!!raw-loader!./_examples/lang.php';
+import langDescription from './_examples/lang.md';
+
+Complete theme options
+
+
+#### `$THEME->blockrtlmanipulations`
+
+Allows the theme to manipulate how the blocks are displayed in a *right-to-left* language. Not recommended CSS is automatically flipped for RTL.
+
+#### `$THEME->csspostprocess`
+
+Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
+
+#### `$THEME->csstreepostprocessor`
+
+
+
+
+
+The first thing Moodle looks at is the name of the layout, in this case it is `standard` (the array key in PHP), it then looks at the settings for the layout, this is the theme, file, regions, and default region. There are also a couple of other options that can be set by a layout:
+
+- `theme` [ *Optional* ]. Is the theme the layout file exists in. That's right: you can make use of layouts from other installed themes.
+- `file` [ *Required* ]. Is the name of the layout file this layout wants to use.
+- `regions` [ *Required* ]. Is the different block regions (places you can put blocks) within the theme.
+- `defaultregion` [ *Required if regions is non-empty, otherwise optional* ]. Is the default location when adding new blocks.
+- `options` [ *Optional* ]. An array of layout specific options described in detail below.
+
+The **theme** is optional. Normally the layout file is looked for in the current theme, or, if it is not there, in the parent theme. However, you can use a layout file from any other theme by giving the theme name here.
+
+You can define whatever regions you like. You just need to pick a name for each one. Most themes just use one or both of `side_pre` and `side_post`, which is like 'left side' and 'right side', except in right to left languages, when they are reversed. If you say in [`config.php`](../theme#configphp) that your the layout provides regions called `fred` and `barney`, then you must call `$OUTPUT->blocks_for_region('fred')` and `$OUTPUT->blocks_for_region('barney')` somewhere in the layout file.
+
+The final setting **options** is a special case that only needs to be set if you want to make use of it. This setting allows the theme designer to specify special options that they would like to create that can be later accessed within the layout file. This allows the theme to make design decisions during the definition and react upon those decisions in what ever layout file is being used.
+
+One such place this has been used is within the boost theme. If you take a look first at `theme/boost/config.php` you will notice that several layouts specify options `langmenu` and `nonavbar` which can both be set to either true or false. The layout options can then be used on the `layout .php` files, mustache templates and renderers.
+
+```php
+layout_options['nonavbar']) && $PAGE->has_navbar());
+$hasfooter = (empty($PAGE->layout_options['nofooter']));
+```
+
+## Layout files
+
+Layout files are used to provide a different layout of the elements of the page for different types of pages in Moodle.
+
+In the [`config.php`](../theme#configphp) for a theme there is a list of **layouts** which map a page type to a specific PHP page in the layout folder for the theme.
+
+View example of one layout definition in config.php
+
+
+```php
+$THEME->layouts = [
+ // Standard layout with blocks, this is recommended for most pages with general information
+ 'standard' => [
+ 'theme' => 'boost',
+ 'file' => 'columns2.php',
+ 'regions' => ['side-pre'],
+ 'defaultregion' => 'side-pre',
+ ],
+],
+```
+
+
+
+
+
+:::tip
+
+It is possible to implement a layout file directly in PHP by echoing the HTML for the page, or mixing PHP tags with HTML, but a better way to create a layout file is to gather all the information required for the layout into a context and render it with a mustache template.
+
+Using templates for layout files makes a lot of sense because they are easier to read and maintain than mixing PHP and HTML in the same file.
+
+[Read about mustache templates](../../../guides/templates/index.md)
+
+:::
+
+View example of layout definition for popup
+
+
+```php title="theme/boost/config.php"
+ 'popup' => [
+ 'file' => 'columns1.php',
+ 'regions' => [],
+ 'options' => ['nofooter' => true, 'nonavbar' => true],
+ ],
+```
+
+This example means every page that has pagetype `popup` will be displayed with the `theme/themename/layout/columns1.php` file, it will have no block regions and there are some options that will be available to the page in the global variable `$PAGE->layout_options`.
+
+
+
+
+
+View example of a layout file using a template
+
+
+```php title="theme/boost/layout/columns1.php"
+body_attributes([]);
+
+$templatecontext = [
+ 'sitename' => format_string($SITE->shortname, true, ['context' => context_course::instance(SITEID), "escape" => false]),
+ 'output' => $OUTPUT,
+ 'bodyattributes' => $bodyattributes
+];
+
+echo $OUTPUT->render_from_template('theme_boost/columns1', $templatecontext);
+```
+
+This example puts some variables into a `templatecontext` and then calls `render_from_template` to render the mustache template for this layout. The template is located at `theme/boost/templates/columns1.mustache`.
+It is possible to put PHP classes in the context for the mustache template and any public properties or methods which accept no arguments will be available to the template. `$OUTPUT` has several useful public methods which accept no arguments and is a valuable class when creating a layout template in mustache.
+
+
+
+
+
+If we had block regions in this layout we would need to insert them in the template. The way we would do this is by getting the HTML for the block region in our layout PHP file, adding it to the context and then including it in our template.
+
+```php title="theme/boost/layout/columns2.php"
+$blockshtml = $OUTPUT->blocks('side-pre');
+$hasblocks = strpos($blockshtml, 'data-block=') !== false;
+...
+$templatecontext = [
+...
+ 'sidepreblocks' => $blockshtml,
+ 'hasblocks' => $hasblocks,
+...
+];
+echo $OUTPUT->render_from_template('theme_boost/columns2', $templatecontext);
+```
+
+```handlebars title="theme/boost/templates/columns2.mustache"
+ {{#hasblocks}}
+ View example of the mustache template for the previous layout
+
+
+```handlebars title="theme/boost/templates/columns1.mustache"
+{{{ output.doctype }}}
+
+
+ {{{ output.page_title }}}
+
+ {{{ output.standard_head_html }}}
+
+
+
+
+
+{{{ output.page_title }}}
+```
+
+- A function is called to obtain the URL to the favicon. The favicon resides in the theme pix directory and is served through the `theme/image.php` file, which adds special caching headers for images.
+
+```handlebars
+
+```
+
+- The standard head HTML function handles a significant amount of necessary setup for our page. It internally creates the block regions, generates meta tags including keywords for SEO, initializes common JavaScript modules, generates links to the style sheets, and injects any additional HTML set by the `$CFG->additionalhtmlhead` setting.
+
+```handlebars
+ {{{ output.standard_head_html }}}
+```
+
+- This `viewport` meta tag is recommended by bootstrap for "proper viewport rendering and touch zooming".
+
+```handlebars
+
+
+```
+
+- The body attributes include the language direction and standard classes for the page.
+
+```handlebars
+
+
+```
+
+- In the Boost theme, a `page-wrapper` div is utilized to prevent content from disappearing under the fixed header.
+
+```handlebars
+
+
+
+ {{{ output.standard_top_of_body_html }}}
+
+
+{{{ output.standard_end_of_body_html }}}
+
+
+{{#js}}
+require(['theme_boost/loader']);
+{{/js}}
+```
+
+Explaining each line of this template will answer a lot of questions. This example contains only the very minimal required functions to generate a valid layout. You should consider all of the sections below as required in every layout file (although any of the HTML tags can and should be altered).
+
+- Calling a function on `$OUTPUT` in `PHP`. Because there is a public method on the output class named `doctype` which accepts no arguments, mustache will call it and return the output. A function to generate the `doctype` tag is called because calling this function returns the correct HTML for the document type for this theme AND it sets a different content type header (including the charset) depending on the doc type for the theme. Setting a correct charset in every page is important to prevent a class of XSS attacks.
+
+```handlebars
+{{{ output.doctype }}}
+```
+
+- The root tag, the HTML tag, has been reintroduced. A set of default attributes for the page has been included by invoking the `htmlattributes` function of the output class. This encompasses the appropriate language attribute for the entire page and potentially an XML namespace for XHTML documents.
+
+```handlebars
+
+```
+
+- The head section of the document has been initiated, and the title for the page has been set. Note that the title is already escaped by the output class, so triple mustache tags `{{{` are being used to prevent double escaping.
+
+```handlebars
+
+
+
+
+
+
+
+
+
+
+ {{{ output.course_content_header }}}
+ {{{ output.main_content }}}
+ {{{ output.course_content_footer }}}
+
+
+```
+
+- The `standard_top_of_body_html` should be included in every layout and includes skip links for accessibility as well as initialising JQuery, YUI and own static JavaScript files.
+
+```handlebars
+ {{{ output.standard_top_of_body_html }}}
+```
+
+- This is standard HTML tags defining the content region for this page. The classes come from Bootstrap 4.
+
+```handlebars
+
+```
+
+- This function will add all of the JavaScript that was required while rendering the page. JavaScript is added at the end of the document so that it does not block rendering the page.
+
+```handlebars
+{{{ output.standard_end_of_body_html }}}
+```
+
+- Finish the HTML for the page.
+
+```handlebars
+
+
+```
+
+- The final section is required for Bootstrap 4 themes and loads all the Bootstrap 4 JavaScript dependencies.
+
+```handlebars
+{{#js}}
+require(['theme_boost/loader']);
+{{/js}}
+```
+
+
+
+
+
+
+
+
+
+
+```
+
+- The course content header allows Moodle plugins to inject things in the top of the page. This is used for "notifications" for example (which are the alert boxes you see after submitting a form).
+
+```handlebars
+ {{{ output.course_content_header }}}
+```
+
+- The main content function returns the real content for the page.
+
+```handlebars
+ {{{ output.main_content }}}
+```
+
+- The course content footer is used mainly by course formats to insert things after the main content.
+
+```handlebars
+ {{{ output.course_content_footer }}}
+```
+
+- Close all the open tags.
+
+```handlebars
+
+ +New theme developers should note that the order in which CSS files are found and included creates a hierarchy. This order ensures that the rules, within a theme's style sheets, take precedence over identical rules in other files that may have been introduced before. This can both extend another files definitions (see parent array in the config file) and also ensures that the current theme's CSS rules/definitions have the last say.
+There are other locations that can be used (although very rarely) to include CSS in a page. A developer of a php file can manually specify a stylesheet from anywhere within Moodle, like the database. Usually, if code is doing this, it is because there is a non-theme config or plugin setting that contains information requires special CSS information. As a theme designer you should be aware of, but not have to worry about, these locations of CSS files. Here are some examples: +- `{pluginpath}\styles.css` (for instance, `\block\blockname\styles.css` or `\mod\modname\styles.css`). Every plugin can have its own styles.css file. This file should only contain the required CSS rules for the module and should not add anything to the look of the plugin such as colours, font sizes, or margins other than those that are truly required.
Theme specific styles for a plugin should be located within the themes styles directory. +- `{pluginpath}\styles_themename.css`. This should only ever be used by plugin developers. It allows them to write CSS that is designed for a specific theme without having to make changes to that theme. You will notice that this is never used within Moodle and is designed to be used only by contributed code. + +:::tip + +As theme designers, only the first method of introducing CSS will be used: adding rules to a stylesheet file located in the theme's style directory. + +::: + +## CSS pre-processors + +Browsers understand CSS well, but it is hard to write and maintain. The language does not support inheritance and reuse. [Support for variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) exists in more modern browsers only. This is why CSS pre-processors were invented. Moodle supports SASS, which is recommended by far. + +:::info Information + +To use SASS, define `$THEME->scss = 'filename';` in your themes `config.php`. Moodle will then use one of it's in-built CSS pre-processor to compile the CSS the first time it is loaded (or every time if `themedesignermode` is enabled in `$CFG`). + +For more information see: [SASS (wikipedia)](https://en.wikipedia.org/wiki/Sass_(stylesheet_language)) + +::: + +## Core CSS organisation + +None of the themes provided in the standard install by Moodle use CSS stylesheets directly. Instead they use either SCSS to generate the style sheets. They all list one main SCSS file named `moodle` or scss folders and this file uses imports to load all other required files. + +:::note + +As a theme designer, it is entirely up to you how you create and organize your CSS and the rules you create. + +::: + +## How to write effective CSS rules within Moodle + +:::warning Important + +Writing good CSS rules is incredibly important. + +::: + +Due to performance requirements and browser limitations, all of the CSS files are combined into a single CSS file that gets included every time. This means that rules need to be written in such a way as to minimise the chances of a collision leading to unwanted styles being applied. Whilst writing good CSS is something most designers strive for we have implemented several new body classes and prompt developers to use appropriate classnames. + +### \
+
+
+:::info
+
+You will notice that the JavaScript is broken down into a number of source files.
+
+This separation is optional, but fits a convention demonstrate in the TinyMCE codebase, and make the code easier to read and understand.
+
+:::
+
+## Creating a new plugin
+
+We highly recommend using the [Plugin Skeleton Generator](https://moodle.org/plugins/tool_pluginskel) when creating a new plugin.
+
+For the sake of simplicity, this documentation assumes that you have created a new Plugin using the following skeleton configuration:
+
+```yml title="tiny_example.yml"
+component: tiny_example
+name: Example Plugin
+release: "0.1.0"
+copyright: 2022 Andrew Lyons The directory layout for the `tiny_example` plugin.
+ +```console +lib/editor/tiny/plugins/example +├── amd +│ ├── build +│ │ ├── commands.min.js +│ │ ├── commands.min.js.map +│ │ ├── common.min.js +│ │ ├── common.min.js.map +│ │ ├── configuration.min.js +│ │ ├── configuration.min.js.map +│ │ ├── options.min.js +│ │ ├── options.min.js.map +│ │ ├── plugin.min.js +│ │ └── plugin.min.js.map +│ └── src +│ ├── commands.js +│ ├── common.js +│ ├── configuration.js +│ ├── options.js +│ └── plugin.js +├── classes +│ ├── plugininfo.php +│ └── privacy +│ └── provider.php +├── lang +│ └── en +│ └── tiny_example.php +├── settings.php +└── version.php +``` + +
+
+
+Typically this file will be included in other JS files in the plugin, usually only fetching the required variables, for example:
+
+```javascript
+import {component, pluginName} from './common';
+```
+
+### plugin.js
+
+The plugin.js is the entrypoint to the plugin code. It is primarily responsible for registering the plugin with the TinyMCE API, and the Moodle Integration of the Editor.
+
+An example common.js file generated by the plugin skeleton generator
+ +This example includes: + +- the plugin name (`tiny_example/plugin`); +- an icon, whose name is `tiny_example`; +- a button for the start demo action, whose name is `tiny_example_startdemo`; and +- a menu item for the start demo action, whose name is `tiny_example_startdemo`. + +```javascript title="commons=.js" +const component = 'tiny_example'; + +export default { + component, + pluginName: `${component}/plugin`, + icon: component, + startdemoButtonName: `${component}_startdemo`, + startdemoMenuItemName: `${component}_startdemo`, +}; +``` + +
+
+
+The plugin can be broadly broken down into several different areas:
+
+#### The default export
+
+Every plugin must return a default export containing a new Promise.
+
+This allows the API to load multiple plugins in parallel with minimal blocking.
+
+```javascript
+// Imports go here.
+export default new Promise(async(resolve) => {
+ // Configure the plugin here.
+
+ // Resolve when the plugin has been configured.
+ resolve([pluginName, Configuration]);
+});
+```
+
+#### Preparation
+
+The TinyMCE API does not support asynchronous code in the plugin registration. Therefore any asynchronous tasks must be complete before registering the plugin with the TinyMCE API, and before resolving the Promise.
+
+In the following example, we fetch the tinyMCE API, a set of plugin metadata to use, and a command setup function to call later on.
+
+```javascript
+// Note: The PluginManager.add function does not support asynchronous configuration.
+// Perform any asynchronous configuration here, and then call the PluginManager.add function.
+const [
+ tinyMCE,
+ pluginMetadata,
+ setupCommands,
+] = await Promise.all([
+ getTinyMCE(),
+ getPluginMetadata(component, pluginName),
+ getCommandSetup(),
+]);
+```
+
+#### Registration of the plugin
+
+Once all of the dependencies are available, we can register the plugin with the TinyMCE PluginManager API.
+
+In this example, we register a plugin whose name is represented as a string in the `pluginName` variable.
+
+Whenever a new editor instance is created, it will call the callback providing the `editor` argument.
+
+At the end of the plugin instantiation, it returns a `pluginMetadata` object, which contains information about the plugin displayed in the help dialogue for the plugin.
+
+```javascript
+// Reminder: Any asynchronous code must be run before this point.
+tinyMCE.PluginManager.add(pluginName, (editor) => {
+ // Register any options that your plugin has
+ registerOptions(editor);
+
+ // Setup any commands such as buttons, menu items, and so on.
+ setupCommands(editor);
+
+ // Return the pluginMetadata object. This is used by TinyMCE to display a help link for your plugin.
+ return pluginMetadata;
+});
+```
+
+In this example, the plugin describes a set of options which will be passed from the PHP description of the plugin - these are handled by the `registerOptions(editor)` call.
+
+It also has a set of 'commands', which are a generic term used to describe any Buttons, MenuItems, and related UI features of the editor.
+
+### commands.js
+
+TinyMCE supports a range of commands. These are further defined in the TinyMCE API: [tinymce.editor.ui.Registry](https://www.tiny.cloud/docs/tinymce/6/apis/tinymce.editor.ui.registry/).
+
+Most plugins will make use of one or more of the following commands, but others are also available:
+
+- [addIcon](https://www.tiny.cloud/docs/tinymce/6/apis/tinymce.editor.ui.registry/#addIcon)
+- [addButton](https://www.tiny.cloud/docs/tinymce/6/apis/tinymce.editor.ui.registry/#addButton)
+- [addToggleButton](https://www.tiny.cloud/docs/tinymce/6/apis/tinymce.editor.ui.registry/#addToggleButton)
+- [addMenuItem](https://www.tiny.cloud/docs/tinymce/6/apis/tinymce.editor.ui.registry/#addMenuItem)
+- [addToggleMenuItem](https://www.tiny.cloud/docs/tinymce/6/apis/tinymce.editor.ui.registry/#addToggleMenuItem)
+
+Plugins may use any parts of the TinyMCE API that they need.
+
+An example plugin.js file generated by the plugin skeleton generator
+ +```javascript title="plugin.js" +import {getTinyMCE} from 'editor_tiny/loader'; +import {getPluginMetadata} from 'editor_tiny/utils'; + +import {component, pluginName} from './common'; +import {register as registerOptions} from './options'; +import {getSetup as getCommandSetup} from './commands'; +import * as Configuration from './configuration'; + +// Setup the tiny_example Plugin. +export default new Promise(async(resolve) => { + // Note: The PluginManager.add function does not support asynchronous configuration. + // Perform any asynchronous configuration here, and then call the PluginManager.add function. + const [ + tinyMCE, + pluginMetadata, + setupCommands, + ] = await Promise.all([ + getTinyMCE(), + getPluginMetadata(component, pluginName), + getCommandSetup(), + ]); + + // Reminder: Any asynchronous code must be run before this point. + tinyMCE.PluginManager.add(pluginName, (editor) => { + // Register any options that your plugin has + registerOptions(editor); + + // Setup any commands such as buttons, menu items, and so on. + setupCommands(editor); + + // Return the pluginMetadata object. This is used by TinyMCE to display a help link for your plugin. + return pluginMetadata; + }); + + resolve([pluginName, Configuration]); +}); +``` + +
+
+
+:::important A note about synchronicity
+
+The TinyMCE `PluginManager.add` function requires all code to be called synchronously - that is to say that all Promises must be resolved before it is called.
+
+See more information on the Editor instance in the [tinymce.Editor](https://www.tiny.cloud/docs/tinymce/6/apis/tinymce.editor/) API documentation.
+
+:::
+
+#### `handleAction(editor)`
+
+The handleAction function is an example of one way in which the various buttons and menu items can handle their activation.
+
+The action passes a reference to the _instance_ of the TinyMCE editor in the `editor` variable.
+
+It should be possible to interact with all required parts fo the TinyMCE API using this value.
+
+#### `getSetup()`
+
+`getSetup()` function in the example above is an asynchronous function which returns a synchronous function.
+
+This is important because the TinyMCE PluginManager API requires all code to be synchronous and already exist.
+
+In this example strings are fetched fro the button and menu titles, and the icon is fetched using a Mustache Template. All of these functions return a Promise and therefore we must wait for them to resolve before returning the function which uses them.
+
+#### The curried setup function
+
+The `getSetup()` function returns a new function which is called from `plugin.js` during the instantiation of _each editor instance_. If you have five editors on a page, then this function is called five times - once per editor instance.
+
+This function is passed a partially-configured [tinymce.Editor](https://www.tiny.cloud/docs/tinymce/6/apis/tinymce.editor/) instance on which it can call the registry commands to define the various buttons.
+
+### Plugin options - `options.js` and `plugininfo.php`
+
+There are often times that you will want to pass options, or values stored in Moodle's PHP API, to the JavaScript API in your plugin. TinyMCE has a detailed API to support parsing and validation of per-instance options which make this relatively easy.
+
+To help make this easier, several helpers exist.
+
+On the PHP side of the API, the `plugininfo.php` file can implement an optional `plugin_with_configuration` interface and define a `get_plugin_configuration_for_context` function:
+
+```php title="lib/editor/tiny/plugins/example/classes/plugininfo.php"
+ 'TODO Calculate your values here',
+ ];
+ }
+}
+```
+
+The values passed in may come from location including as site configuration values (that is `get_config()`), values based on capabilities, or values based on the `$options` passed in.
+
+On the JavaScript side of the API, an `options.js` file is used to handle parsing, validation, and fetching of the values.
+
+An example commands.js file generated by the plugin skeleton generator
+ +```javascript tilte="commands.js" +import {getButtonImage} from 'editor_tiny/utils'; +import {get_string as getString} from 'core/str'; +import { + component, + startdemoButtonName, + startdemoMenuItemName, + icon, +} from './common'; + +/** + * Handle the action for your plugin. + * @param {TinyMCE.editor} editor The tinyMCE editor instance. + */ +const handleAction = (editor) => { + // TODO Handle the action. + window.console.log(editor); +}; + +export const getSetup = async() => { + const [ + startdemoButtonNameTitle, + startdemoMenuItemNameTitle, + buttonImage, + ] = await Promise.all([ + getString('button_startdemo', component), + getString('menuitem_startdemo', component), + getButtonImage('icon', component), + ]); + + return (editor) => { + // Register the Moodle SVG as an icon suitable for use as a TinyMCE toolbar button. + editor.ui.registry.addIcon(icon, buttonImage.html); + + // Register the startdemo Toolbar Button. + editor.ui.registry.addButton(startdemoButtonName, { + icon, + tooltip: startdemoButtonNameTitle, + onAction: () => handleAction(editor), + }); + + // Add the startdemo Menu Item. + // This allows it to be added to a standard menu, or a context menu. + editor.ui.registry.addMenuItem(startdemoMenuItemName, { + icon, + text: startdemoMenuItemNameTitle, + onAction: () => handleAction(editor), + }); + }; +}; +``` + +
+
+
+
+After being passed from the PHP API, the Moodle integration names properties according to the plugin from which they originate. In order to fetch the value out, you must use the `getPluginOptionName()` function to translate this value.
+
+```javascript title="Getting the namespaced option name"
+const myFirstPropertyName = getPluginOptionName(pluginName, 'myFirstProperty');
+```
+
+Before being set, or fetched back out, each property must be registered with the TinyMCE API. This is done for each _instance_ of the editor:
+
+```javascript title="Registering the option"
+export const register = (editor) => {
+ const registerOption = editor.options.register;
+
+ // For each option, register it with the editor.
+ // Valid type are defined in https://www.tiny.cloud/docs/tinymce/6/apis/tinymce.editoroptions/
+ registerOption(myFirstPropertyName, {
+ processor: 'string',
+ });
+};
+```
+
+:::info
+
+See the [tinymce.EditorOptions](https://www.tiny.cloud/docs/tinymce/6/apis/tinymce.editoroptions/) API documentation for further details on the `register` method.
+
+:::
+
+Finally, it is recommended that you then create helpers to fetch the values back out.
+
+```javascript title="Retrieving the stored value"
+export const getMyFirstProperty = (editor) => editor.options.get(myFirstPropertyName);
+```
+
+:::info
+
+Editor options are specific to an _instance_ of the editor, therefore the `editor` must be passed as an argument.
+
+:::
+
+You may have multiple helpers, for example you may have a helper to process the value and return a boolean state of the value.
+
+```javascript title="Processing an option"
+export const hasMyFirstProperty = (editor) => editor.options.isSet(myFirstPropertyName);
+```
+
+### Editor configuration - `configuration.js`
+
+The TinyMCE Editor only allows for very minimal configuration by administrators. This is a deliberate decision made to reduce the complexity of the User Interface, and to encourage consistency.
+
+To support this, for a plugin to place commands (that is buttons, and menu items) in the User Interface, they must modify the TinyMCE configuration.
+
+The TinyMCE [Menus](https://www.tiny.cloud/docs/tinymce/6/menus-configuration-options/#menu) and [Toolbar](https://www.tiny.cloud/docs/tinymce/6/toolbar-configuration-options/) configuration describes the expected format of this configuration.
+
+In order to make your configuration changes you must create a `Configuration` object, which contains a `configure()` function. This value should be resolved at the end of your `plugin.js` file, for example:
+
+```javascript title="Defining a Configuration"
+import * as Configuration from './configuration';
+
+export default new Promise(async(resolve) => {
+ // ... Plugin code goes here.
+
+ resolve([pluginName, Configuration]);
+})
+```
+
+The Moodle TinyMCE Integration will call `Configuration.configure` after the initial editor configuration has been put in place.
+
+The `configure` function is passed the current configuration and must return an object which is merged into the configuration.
+
+For example, to add an item to the 'content' toolbar region, you would define your `configure` function return an Object containing the `toolbar` key:
+
+```javascript title="configuration.js"
+export const configure = (instanceConfig) => {
+ return {
+ toolbar: addToolbarButtons(instanceConfig.toolbar, 'content', buttonName),
+ };
+};
+```
+
+This is used to replace any matching keys in the existing `instanceConfig`.
+
+:::note
+
+The above example makes use of a helper from the `editor_tiny/utils` module, which contains a number of useful helpers.
+
+:::
+
+A complete example of the options.js implementation
+ +```javascript title="lib/editor/tiny/plugins/example/amd/src/options.js" +import {getPluginOptionName} from 'editor_tiny/options'; +import {pluginName} from './common'; + +// Helper variables for the option names. +const myFirstPropertyName = getPluginOptionName(pluginName, 'myFirstProperty'); + +/** + * Options registration function. + * + * @param {tinyMCE} editor + */ +export const register = (editor) => { + const registerOption = editor.options.register; + + // For each option, register it with the editor. + // Valid type are defined in https://www.tiny.cloud/docs/tinymce/6/apis/tinymce.editoroptions/ + registerOption(myFirstPropertyName, { + processor: 'number', + }); +}; + +/** + * Fetch the myFirstProperty value for this editor instance. + * + * @param {tinyMCE} editor The editor instance to fetch the value for + * @returns {object} The value of the myFirstProperty option + */ +export const getMyFirstProperty = (editor) => editor.options.get(myFirstPropertyName); +``` + +
+
+
+
+## CSS styles
+
+CSS styles that apply to the editor controls and its popup windows can be placed in the normal Moodle `styles.css` file, because these controls are part of the normal Moodle page.
+
+If there are styles that need to apply to the actual content being edited, this appears in a separate iframe so the normal styles have no effect. These styles should be placed in a file called `editor_styles.css`. You might need to do this if your plugin inserts HTML within the content such as a custom `` tag which needs particular styling.
+
+:::note
+
+Care should be taken when adding content styles so that generated content is not tied to the editor plugin. If the plugin is removed (or users choose a different editor), it should not break content.
+
+:::
diff --git a/versioned_docs/version-5.1/apis/plugintypes/tiny/testing.md b/versioned_docs/version-5.1/apis/plugintypes/tiny/testing.md
new file mode 100644
index 0000000000..b08ca16a41
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/plugintypes/tiny/testing.md
@@ -0,0 +1,181 @@
+---
+title: Testing
+tags:
+ - editor_tiny
+ - tiny
+ - Editor
+ - Behat
+ - Testing
+---
+
+Testing is an important part of development and we strongly encourage you to write appropriate tests for your plugins.
+
+:::note
+
+When writing tests which only _use_ a text editor, and are not either tests specifically for that editor, or one of its plugins, you should attempt not to use editor-specific tests.
+
+:::
+
+## Behat
+
+### Tags
+
+If you are writing a test for the TinyMCE editor, please note that your test **must** have one or more of the following Behat tags:
+
+- `@editor_tiny`
+- `@tiny_[pluginname]`
+
+By using these tags appropriately, Moodle will ensure that TinyMCE is set as the default editor for the site for the duration of your test, regardless of any other editors installed.
+
+### Useful steps
+
+A number of useful Behat steps have been defined in [TinyMCE Behat context](https://github.com/moodle/moodle/blob/main/lib/editor/tiny/tests/behat/behat_editor_tiny.php).
+
+:::caution Use generic steps where possible
+
+Typically, when interacting with an Editor, you should use the _generic_ step definitions rather than writing specific steps, or writing sequences of steps to do so.
+
+:::
+
+#### Generic steps to interact with editors
+
+Most of these steps are defined in the [Behat Forms context](https://github.com/moodle/moodle/blob/main/lib/tests/behat/behat_forms.php) and this documentation should not be treated as a complete list, rather an indication of approaches that you may consider taking.
+
+##### Setting content of a field
+
+```gherkin title="Set the content of the field with the label 'Description'"
+Given I set the field "Description" to "A complete example of configuring a menu and toolbar for tiny_example
+ +```javascript title="configuration.js" + +import { + startdemoButtonName, + startdemoMenuItemName, +} from './common'; + +import { + addMenubarItem, + addToolbarButtons, +} from 'editor_tiny/utils'; + +const getToolbarConfiguration = (instanceConfig) => { + let toolbar = instanceConfig.toolbar; + toolbar = addToolbarButtons(toolbar, 'content', [ + startdemoButtonName, + ]); + + return toolbar; +}; + +const getMenuConfiguration = (instanceConfig) => { + let menu = instanceConfig.menu; + menu = addMenubarItem(menu, 'file', [ + startdemoMenuItemName, + ].join(' ')); + + return menu; +}; + +export const configure = (instanceConfig) => { + return { + toolbar: getToolbarConfiguration(instanceConfig), + menu: getMenuConfiguration(instanceConfig), + }; +}; +``` + +Some value which includes valid HTML
" +Given I set the field "Description" to multiline: +""" +Some value which includes valid HTML
+""" +``` + +```gherkin title="Set the content of the field with the label 'Description' within the 'Create event' modal" +Given I set the field "Description" in the "Create event" "dialogue" to "Some value which includes valid HTML
" +``` + +```gherkin title="Set the content of the field with the label 'Description' along side some other fields" +Given I set the following fields to these values: + | Name | Some name here | + | Description |Some value which includes valid HTML
| +``` + +```gherkin title="Set the content of the field with the label 'Description' along side some other fields within the 'Create event' modal" +Given I set the following fields in the "Create event" "dialogue" to these values: + | Name | Some name here | + | Description |Some value which includes valid HTML
| +``` + +##### Checking the content of a field + +```gherkin title="Check that the content of the field with the label 'Description' matches a value" +Then the field "Description" matches value "Some value which includes valid HTML
" +Then the field "Description" matches multiline: +""" +Some value which includes valid HTML
+""" +``` + +```gherkin title="Check that the content of the field with the label 'Description' does not match a value" +Then the field "Description" does not match value "Some value which includes valid HTML
" +``` + +```gherkin title="Check that the content of the field with the label 'Description' within the 'Create event' modal matches a value" +Then the field "Description" in the "Create event" "dialogue" matches value "Some value which includes valid HTML
" +``` + +```gherkin title="Check that the content of a set of fields match values" +Then the following fields match these values: + | Name | Some name here | + | Description |Some value which includes valid HTML
| +``` + +```gherkin title="Check that the content of a set of fields within the 'Create event' modal match values" +Then the following fields in the "Create event" "dialogue" match these values: + | Name | Some name here | + | Description |Some value which includes valid HTML
| +``` + +#### TinyMCE specific steps + +If you are writing a TinyMCE plugin or feature, then you may need to interact with the editor interface, or to check and set the current value of the editor. + +:::note iFrames + +Behat makes use of WebDriver to control browsers. The WebDriver specification limits the scope of a command to the current _context_ where a context is a browser Window, Frame, or iFrame. + +TinyMCE places the Editor UI within its own iFrame. To control any of its interface, you _may_ need to switch to the iFrame for your editor first. + +Most of the steps written for TinyMCE are already aware of the iFrame. + +::: + +##### Working with toolbar buttons + +```gherkin title="Expanding all toolbar buttons" +Given I expand all toolbars for the "Description" TinyMCE editor +``` + +:::caution + +The default TinyMCE configuration will automatically collapse the toolbar to show as many elements as will fit on the page. + +You should always use the "I expand all toolbars" step before interacting with a button on the toolbar as it may not be visible in all cases. + +This step is safe to call if the toolbar is already expanded, or does not need to be expanded. + +::: + +```gherkin title="Clicking on a button for your editor" +When I click on the "Bold" button for the "Description" TinyMCE editor +``` + +```gherkin title="Checking the state of a button in your editor" +Then the "Bold" button of the "Description" TinyMCE editor has state "true" +``` + +##### Working with the menu bar + +```gherkin title="Clicking on a menu bar button" +I click on the "Insert" menu item for the "Description" TinyMCE editor +``` + +```gherkin title="Clicking on a nested menu bar button" +I click on the "Insert > Image" menu item for the "Description" TinyMCE editor +``` + +##### Selecting content + +```gherkin title="Selecting content by tag name and index" +I select the "p" element in position "2" of the "Description" TinyMCE editor +``` + +```gherkin title="Selecting content using a selector and type" +I select the ".example_placeholder" "css_element" in the "Description" TinyMCE editor +``` + +:::note + +All content selection is performed within the context of the editor's own iframe. Please note that some of the standard Behat locators will not work as they expect certain elements to be present within the page body. + +::: + +### Writing your own steps + +If you are writing your own steps, then we recommend that you: + +- include the name of your plugin, or "TinyMCE editor" in the wording of the step so that it is not mis-used for another purpose +- check that the Feature, or Scenario, includes the frankenstyle component name for your plugin + +```php title="Checking for a tag on your Feature or Scenario" +if (!$this->has_tag('tiny_myplugin')) { + throw new DriverException( + 'This step must have the @tiny_myplugin tag on either the Feature, or the Scenario.' + ); +} +``` + +### Important notes + +Some of these steps will be improved in coming changes. See MDL-75926 and MDL-76853 for more information. diff --git a/versioned_docs/version-5.1/apis/subsystems/_category_.yml b/versioned_docs/version-5.1/apis/subsystems/_category_.yml new file mode 100644 index 0000000000..5586419cca --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/_category_.yml @@ -0,0 +1,3 @@ +label: Subsystems +link: + type: generated-index diff --git a/versioned_docs/version-5.1/apis/subsystems/_roles/Moodle-contexts-1.8.png b/versioned_docs/version-5.1/apis/subsystems/_roles/Moodle-contexts-1.8.png new file mode 100644 index 0000000000..18e8fc4001 Binary files /dev/null and b/versioned_docs/version-5.1/apis/subsystems/_roles/Moodle-contexts-1.8.png differ diff --git a/versioned_docs/version-5.1/apis/subsystems/access.md b/versioned_docs/version-5.1/apis/subsystems/access.md new file mode 100644 index 0000000000..28e85e6e54 --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/access.md @@ -0,0 +1,235 @@ +--- +title: Access API +tags: + - Access +--- + + + +The Access API gives you functions so you can determine what the current user is allowed to do. It also allows plugins to extend Moodle with new capabilities. + +## Overview + +Moodle uses a role-based access control model. Entities are represented by contexts which are arranged into a tree-like hierarchy known as the context tree. + +The following context types are available: + +| Context name | Represents | Immediate contents | Notes | +| --- | --- | --- | --- | +| `context_system` | The site as a whole | user, course category, module, and block | The System context is root context in the tree. There is only one System context | +| `context_user` | An individual user | block | Each user has their own, unique, context | +| `context_coursecat` | A single course category | course category, course, block | | +| `context_course` | A single course | module, block | | +| `context_module` | An activity | block | | +| `context_block` | A block | none | | + +A Role is a set of capability definitions, where each capability represents something that the user is able to do. Roles are defined at the top most +context in the context tree, the System context. + +Roles can be overridden by contexts further down the tree. + +User access is calculated from the combination of roles which are assigned to each user. + +All users that did not log-in yet automatically get the default role defined in `$CFG->notloggedinroleid`, it is not possible to assign any other role to this non-existent user id. There is one special guest user account that is used when user logs in using the guest login button or when guest auto-login is enabled. Again you can not assign any roles to the guest account directly, this account gets the `$CFG->guestroleid` automatically. All other authenticated users get the default user role specified in `$CFG->defaultuserroleid` and in the frontpage context the role specified in `$CFG->defaultfrontpageroleid`. + ++Provides the activity task class +- **backup_foobar_stepslib.php**
+Provides all the backup steps classes + +If your module declares its own backup setting (apart from the ones common for all activity modules provided by the core), you will also want to create the backup_foobar_settingslib.php file to provide the setting classes. However most modules do not need this feature. + +### Backup task class + +The file backup_foobar_activity_task.class.php must provide a single class called **backup_foobar_activity_task**. All activity tasks extend the backup_activity_task class. + +There are three methods that your class must define. + +- **protected function define_my_settings()**
+If your module declares own backup settings defined in the file backup_foobar_settingslib.php, add them here. Most modules just leave the method body empty. +- **protected function define_my_steps()**
+This method typically consists of one or more `$this->add_step()` calls. This is the place where you define the task as a sequence of steps to execute. +- **static public function encode_content_links($content)**
+The current instance of the activity may be referenced from other places in the course by URLs like `http://my.moodle.site/mod/foobar/view.php?id=42` Obviously, such URLs are not valid any more once the course is restored elsewhere. For this reason the backup file does not store the original URLs but encodes them into a transportable form. During the restore, the reverse process is applied and the encoded URLs are replaced with the new ones valid for the target site. + +### Backup structure step class + +The classes that represent the backup steps added in define_my_steps() are implemented in the file backup_foobar_stepslib.php. Most plugins define just a single step in the class called **backup_foobar_activity_structure_step** that extends the backup_activity_structure_step class. This class defines the structure step - that is the step where the structure of your plugin's instance data is described and linked with the data sources. + +You have to implement a single method `protected function define_structure()` in this class class. There are three main things that the method must do. + +- Create a set of backup_nested_element instances that describe the required data of your plugin +- Connect these instances into a hierarchy using their `add_child()` method +- Set data sources for the elements, using their methods like `set_source_table()` or `set_source_sql()` + +The method must return the root backup_nested_element instance processed by the `prepare_activity_structure()` method (which just wraps your structures with a common envelope). + +## API for blocks + +### Files + +The files that implement the backup support in your block must be located in the subdirectory backup/moodle2/ in your plugin's folder. So, if you are developing the block called *foobar* then the backup files will be located in blocks/foobar/backup/moodle2/ folder. + +At least the file backup_foobar_block_task.class.php is supposed to exist in that location (replace *foobar* with the name of your block). + +If your block defines its own database tables, data from which must be included in the backup, you will want to create a file backup_foobar_stepslib.php, too. Additionally, if your block declares its own backup setting, you will also want to create the backup_foobar_settingslib.php file to provide the setting classes. However most blocks do not need this feature. + +### Backup task class + +The file backup_foobar_block_task.class.php must provide a single class called **backup_foobar_block_task**. All block tasks extend the backup_block_task class. + +There are five methods that your class must define. + +- **protected function define_my_settings()**
+If your block declares own backup settings defined in the file backup_foobar_settingslib.php, add them here. Most blocks just leave the method body empty. +- **protected function define_my_steps()**
+Blocks that do not have their own database tables usually leave this method empty. Otherwise this method consists of one or more `$this->add_step()` calls where you define the task as a sequence of steps to execute. +- **public function get_fileareas()**
+Returns the array of file area names within the block context. +- **public function get_configdata_encoded_attributes()**
+Instead of using their own tables, blocks usually use the configuration tables to hold their data (see the instance_config_save() of the block class). This method returns the array of all config elements that must be processed before they are stored in the backup. This is typically used when the stored config elements holds links to embedded media. Most blocks just return empty array here. +- **static public function encode_content_links($content)**
+If the current instance of the block may be referenced from other places in the course by URLs, it must be encoded into a transportable form. Most blocks just return unmodified $content parameter. + +## API for admin tools + +The files that implement the backup support in your plugin must be located in the subdirectory *backup/moodle2/* in your plugin's folder. So, if you are developing *tool_foobar* then the backup files will be located in *admin/tool/foobar/backup/moodle2/*. + +### Task class + +The file backup_tool_foobar_plugin.class.php must provide a single class called *backup_tool_foobar_task* extending *backup_tool_plugin*. + +Here is a minimalistic task: + +```php +require_once($CFG->dirroot . '/backup/moodle2/backup_tool_plugin.class.php'); + +class backup_tool_foobar_plugin extends backup_tool_plugin { + + protected function define_course_plugin_structure() { + $this->step->log('Yay, backup!', backup::LOG_DEBUG); + return $plugin; + } + +} +``` + +## API for themes + +See [Backup 2.0 theme data](https://docs.moodle.org/dev/Backup_2.0_theme_data) + +## API for reports + +See [Backup 2.0 course report data](https://docs.moodle.org/dev/Backup_2.0_course_report_data) + +## See also + +- [Restore API](./restore.md) +- [Core APIs](../../../apis.md) diff --git a/versioned_docs/version-5.1/apis/subsystems/backup/restore.md b/versioned_docs/version-5.1/apis/subsystems/backup/restore.md new file mode 100644 index 0000000000..10539c31dc --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/backup/restore.md @@ -0,0 +1,58 @@ +--- +title: Restore API +tags: + - Subsystem + - API + - Backup +--- +The Restore API provides a way to restore your plugin's data from a backup file created in Moodle 2.0 or later. For the information on how backup files are created, see [Backup API](./index.md). For the information on how to support restoring data from backup files created in Moodle 1.x, see [Backup conversion API](https://docs.moodle.org/dev/Backup_conversion_API). + +## Overview + +This page provides just a quick reference to the restore machinery in Moodle 2.0 and higher. There is a detailed documentation available at [Backup 2.0](https://docs.moodle.org/dev/Backup_2.0) page - see especially the tutorial for plugin authors at [Restore 2.0 for developers](https://docs.moodle.org/dev/Restore_2.0_for_developers) page. + +Moodle restores data from course backups by executing so called *restore plan*. The restore plan consists of a set of *restore tasks* and finally each restore task consists of one or more *restore steps*. You as the developer of a plugin will have to implement one restore task that deals with your plugin data. Most plugins have their restore tasks consisting of a single restore step - the one that parses the plugin XML file and puts the data into its tables. + +## API for activity modules + +### Files + +The files that implement the restore support in your activity module must be located in the subdirectory `backup/moodle2/` in your plugin's folder (yes, it's the same folder where the backup related files are located). So, if you are developing the activity module called *foobar* then the restore files will be located in `mod/foobar/backup/moodle2/` folder. + +The following two files are supposed to exist in that location (replace *foobar* with the name of your module): + +- **restore_foobar_activity_task.class.php**
+Provides the activity task class +- **restore_foobar_stepslib.php**
+Provides all the restore steps classes + +(to be continued) + +## API for admin tools + +The files that implement the backup support in your plugin must be located in the subdirectory `backup/moodle2/` in your plugin's folder. So, if you are developing `tool_foobar` then the backup files will be located in `admin/tool/foobar/backup/moodle2/`. + +### Task class + +The file `backup_tool_foobar_plugin.class.php` must provide a single class called `restore_tool_foobar_task` extending `restore_tool_plugin`. + +Here is a minimalistic task: + +```php +require_once($CFG->dirroot . '/backup/moodle2/restore_tool_plugin.class.php'); + +class restore_tool_foobar_plugin extends restore_tool_plugin { + + protected function define_course_plugin_structure() { + $paths = array(); + $this->step->log('Yay, restore!', backup::LOG_DEBUG); + return $paths; + } + +} +``` + +## See also + +- [Core APIs](../../../apis.md) +- [Backup API](../backup) diff --git a/versioned_docs/version-5.1/apis/subsystems/check/index.md b/versioned_docs/version-5.1/apis/subsystems/check/index.md new file mode 100644 index 0000000000..4e6866851a --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/check/index.md @@ -0,0 +1,247 @@ +--- +title: Check API +tags: + - API +--- + +A _Check_ is a runtime test to make sure that something is working well. You can think of Checks as similar and complimentary to the [PHPUnit](/general/development/tools/phpunit) and [Acceptance testing](/general/development/tools/behat) but the next layer around them, and performed at run time rather than development, or build time. + +Like other forms of testing the tests themselves should be easy to read, to reason about, and to confirm as valid. + +:::note + +Many types of runtime checks cannot be unit tested, and often the checks **are** the test. + +::: + +Checks can be used for a variety of purposes including: + +- configuration checks +- security checks +- status checks +- performance checks +- health checks + +Moodle has had various types of checks and reports for a long time but they were inconsistent and not machine readable. In Moodle 3.9 they were unified under a single Check API which also enabled plugins to cleanly define their own additional checks. Some examples include: + +- a password policy plugin could add a security check +- a custom authentication plugin can add a check that the upstream identity system can be connected to +- a MUC store plugin could add a performance check +Having these centralized and with a consistent contract makes it much easier to ensure the whole system is running smoothly. This makes it possible for an external integration with monitoring systems such as Nagios / Icinga. The Check API is exposed as an NPRE compliance cli script: + +```console +php admin/cli/checks.php +``` + +## Result states of a check + +| Status | Meaning | Example | +| --- | --- | --- | +| N/A | This check doesn't apply - but we may still want to expose the check | secure cookies setting is disabled because site is not https | +| Ok | A component is configured, working and fast. | ldap can bind and return value with low latency | +| Info | A component is OK, and we may want to alert the admin to something non urgent such as a deprecation, or something which needs to be checked manually. | | +| Unknown | We don't yet know the state. eg it may be very expensive so it is run using the Task API and we are waiting for the answer. NOTE: unknown is generally a bad thing and is semantically treated as an error. It is better to have a result of Unknown until the first result happens, and from then on it is Ok, or perhaps Warning or Error if the last known result is getting stale. If you are caching or showing a stale result you should expose the time of this in the result summary text. | A complex user security report is still running for the first time. | +| Warning | Something is not ideal and should be addressed, eg usability or the speed of the site may be affected, but it may self heal (eg a load spike) | auth_ldap could bind but was slower than normal | +| Error | Something is wrong with a component and a feature is not working | auth_ldap could not connect, so users cannot start new sessions | +| Critical | An error which is affecting everyone in a major way | Cannot read site data or the database, the whole site is down | + +How the various states are then leveraged is a local decision. A typical policy might be that health checks with a status of 'Error' or 'Critical' will page a system administrator 24/7, while 'Warning' only pages during business hours. + +## Check types and reports + +Checks are broken down into types, which roughly map to a step in the life cycle of your Moodle System. + +### Environmental checks + +Available from _/admin/environment.php_, environmental checks make sure that a Moodle instance is fully configured. + +This page is a potential candidate to move to the new Check API but it slightly more complex than the other checks so it hasn't been tackled yet. It would be a deeper change and this is intrinsically part of the install and upgrade system. It is not as critical to refactor as it is already possible for a plugin to declare its own checks, via either declarative [Environment checking](https://docs.moodle.org/dev/Environment_checking) or programmatically with a custom check: + +### Configuration checks + +Available from _/admin/index.php?cache=1_, the Admin notifications page performs a mixture of checks, including security, status, and performance checks. + +None of these checks are as exhaustive as the checks in the reports below. It also does additional checks including whether the web services for the Moodle Mobile App are enabled, and whether the site has been registered. + +### Security checks (security) + +Available from _/report/security/index.php_, these checks make sure that a Moodle instance is hardened correctly for your needs. + +For more information see [MDL-67776](https://moodle.atlassian.net/browse/MDL-67776). + +### Status checks (status) + +Available from _/report/status/index.php_, a status check is an 'in the moment' test and covers operational tests such as 'can moodle connect to ldap'. The main core status checks are that cron is running regularly and there has been no failed tasks. + +:::danger Important + +It is critical to understand that Status checks are conceptually defined at the level of the application and not at a lower host level such as a docker container or node in a cluster. Checks should be defined so that whichever instance you ask you should get a consistent answer. DO NOT use the Status Checks to detect containers which need to be reaped or restarted. If you do, any status errors may mean all containers will simultaneously be marked for reaping. + +An additional status check is likely the most common type of check a plugin would define. Especially a plugin that connects to a 3rd party service. If the concept of 'OK' requires some sort of threshold, eg network response within 500ms, then that threshold should be managed by the plugin and optionally exposed as a admin setting. The plugin may choose to have different thresholds for Warning / Error / Critical. When designing a new Status Check be mindful that it needs to be actionable, for instance if you are asserting that a remote domain is available and it goes down, which then alerts your infrastructure team, there isn't much they can do about it if it isn't their domain. If it is borderline then make things like this configurable so that each site has to option of tune their own policies of what should be considered an issue or not. + +::: + +For more information see [MDL-47271](https://moodle.atlassian.net/browse/MDL-47271). + +### Performance checks (performance) + +Available from _/report/performance/index.php_, each check might simply check for certain settings which are known to slow things down, or it might actually do some sort of test like multiple reads and writes to the db or filesystem to get a performance metric. + +## Implementing a new check + +### A check class + +And make a new check class in `mod/myplugin/classes/check/foobar.php` and the only mandatory method is `get_result()`. By default it will use a set language string but you can override the `get_name()` method to reuse an existing string. + +```php title="mod/myplugin/lang/en/myplugin.php" +$string['checkfoobar'] = 'Check the foos to make sure they are barred'; +``` + +```php title="mod/myplugin/classes/check/foobar" +id = "foobar{$id}"; + } + + public function get_id(): string { + return $this->id; + } + ... +} +``` + +### Make checks as fast as practical + +As many checks will be run and compiled into a report we want the checks themselves to be simple and as fast as possible. For instance an auth_ldap check while authenticating an end user could have a timeout of 60 seconds, and the check could warn if it takes more than 2 seconds. But the check could have a hard timeout of say 5 seconds and have a result status of ERROR for 5 or more seconds. + +### Lazy loading expensive result details + +Checks can provide details on a check, such as the complete list of bad records. Generally this type of information might be expensive to produce so you can defer this lookup until get_details() is called specifically rather than setting this in the constructor. It will only be loaded on demand and shown when you drill down into the check details page. + +```php +add(new admin_setting_check( + 'antivirus/checkantivirus', + new \core\check\environment\antivirus(), +)); +``` + +:::info + +These checks are performed asynchronously, and only if the check is visible, so will not slow down the whole admin tree which is often a downside of implementing this manually. + +::: + +You can also use checks which are not linked into one of the reports. This means you can check the connection while configuring the plugin, but before it is enabled, and only add the check to the status report page once the plugin is enabled. + +## See also + +- [Performance overview](https://docs.moodle.org/en/Performance_overview) user docs diff --git a/versioned_docs/version-5.1/apis/subsystems/communication/index.md b/versioned_docs/version-5.1/apis/subsystems/communication/index.md new file mode 100644 index 0000000000..de1de2579f --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/communication/index.md @@ -0,0 +1,318 @@ +--- +title: Communication API +tags: + - communication + - provider + - Communication provider + - Communication room + - Communication service + - Chat +documentationDraft: true +--- + +Communication API provides access to the messaging system and other communication providers (such as Matrix). +This API the management of room and members to that room. + +Communication API actions its tasks happens asynchronously using ad-hoc tasks. This means that the API functions will return immediately and the action will be +executed in the background. Communication API has multiple interfaces which acts like a feature of the API. Each of these interface/features have one or more associated +ad-hoc tasks. These tasks are responsible to action the requested feature from the provider plugin (such as Matrix) informed by the Communication API instance. For developers +to interact with the API, they must use the public API (`communication\api`). + +Communication API allows to add ad-hoc tasks to the queue to perform actions on the communication providers. This API will not allow any immediate actions to be performed on the +communication providers. It will only add the tasks to the queue. The exception has been made for deletion of members in case of deleting the user. This is because the user will +not be available for any checks (capability, role etc.) after deleted. + +:::info + +This is an experimental feature. To use this feature, you must enable the experimental feature flag for Communication in the site administration. +Please follow the steps to enable the feature. + +1. Navigate to `Site administration > Development > Experimental` settings. +2. Tick the checkbox to enable the following feature: Enable communication providers (`enablecommunicationsubsystem`). + +::: + +## Hooks + +The Communication API takes advantage of the [Hooks API](../../plugintypes/communication/index.md) with actions performed in the following way: + +1. Actions in core have their own hook dispatched (for example enrol, change role, add to group). +2. Hooks are then registered to a particular callback (`lib/db/hooks.php`). +3. Callbacks are then listened for inside the Communication API's hook listener (`communication\hook_listener`) where all the logic is performed. +4. To identify the ones Communication API is using, the callbacks will be methods from Communication API's hook listener (`communication\hook_listener`). + +## Important features of the API + +The below are the important methods/features of the API. These methods/features are the ones which can be used to interact with the communication API. + +### Loading a communication instance + +To load a communication instance, you must use the `communication\api::load_by_instance()` method. This method will return a communication instance which can be +used to interact with the communication API and its related methods. The below example shows how to load a communication instance for a course, where the +context is the actual course context object, component is the component name (`core_course`), instance type is the custom string which can change according to +the usage and instance id is the course id. The constructor of the public api is private and hence the only way to load an instance is through +the `load_by_instance()` method. The provider is the name of the provider plugin which is used to load the instance. It's optional, if not provided, it will load +the enabled provider for that instance. + +```php +$communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $courseid, + provider: 'communication_matrix', +); +``` + +### Create and configure a room + +`$communication->create_and_configure_room()` method is used to add an ad-hoc to create a room in the communication provider and configure it with the required settings. + +```php +public function create_and_configure_room( + string $communicationroomname, + ?\stored_file $avatar = null, + ?\stdClass $instance = null, +); +``` + +This method takes the following parameters: + +- The name of the room as a string to be created. +- The avatar of the room to be created, this is a stored file object. +- The instance object of the communication API. + +For example, we want to create a room for a course with the course name as the room name and the course image as the avatar, we can use the below code. +There can be other cases where information from course instance will be used by a plugin, for example, the dynamic field from matrix plugin has a form +field named topic which sets the topic of the room, the instance object can be used to get the topic from the course instance and set it in the form field. +Please refer to [Communication plugin](../../plugintypes/communication/index.md) documentation for more details. + +```php +// First initialize the communication instance, +// provided the context is already initialized +// and the selected provider is available +// though a form or other means. +$communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $course->id, + provider: 'communication_matrix', +); + +// Now call the create_and_configure_room() method +// to add an ad-hoc to create a room in the +// communication provider and configure it with the +// required settings. +$communication->create_and_configure_room( + communicationroomname: $course->fullname, + avatar: $courseimage ?: null, + instance: $course, +); +``` + +### Update a room and its associated information + +`$communication->update_room()` method is used to add an ad-hoc to update a room in the communication provider and configure it with the required settings. + +```php +public function update_room( + ?int $active = null, + ?string $communicationroomname = null, + ?\stored_file $avatar = null, + ?\stdClass $instance = null, +); +``` + +This method takes the following parameters: + +- The active status of the room to be updated. Can be either 0 or 1. +- The name of the room as a string to be updated. +- The avatar of the room to be updated, this is a stored file object. +- The instance object of the communication API. + +```php +// First initialize the instance. +$communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $course->id, + provider: 'communication_matrix', +); + +// Now update the room with the required settings. +// The instance will be used by dynamic fields feature of the plugin +// to allow the plugin to get the required information from the instance. +$communication->update_room( + active: $active, + communicationroomname: $communicationroomname, + avatar: $courseimage ?: null, + instance: $course, +); +``` + +### Delete a room + +`$communication->delete_room()` method is used to add an ad-hoc to delete a room in the communication provider. The associated task for this also removes all the members from +the room before deleting the room. + +:::danger + +This is destructive and might remove all the messages and other data associated with the room. Usage of this should be done with caution. + +::: + +### Create and configure a room according to the provider + +There are cases where the provider is changed for a communication instance. +For example, previously the provider was set to _Provider B_ and now it has changed to _Provider A_. +In this case, the room and its members need to be configured according to the new provider. Without any extra logic needed, the method `$communication->configure_room_and_membership_by_provider()` takes care of this in the following way: + +1. Communication provider is changed from _Provider B_ to _Provider A_. +2. New room is created in _Provider A_. +3. Members are added to the new room at _Provider A_. +4. Members are removed from the old room at _Provider B_. + +```php +// First initialize the instance. +$communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $course->id, + provider: 'communication_matrix', + ); + +// Now call this with the new provider to take care of the room and its members for the new provider. +$communication->configure_room_and_membership_by_provider( + provider: 'communication_slack', + instance: $course, + communicationroomname: $coursecommunicationroomname, + users: $enrolledusers, + instanceimage: $courseimage, + ); +``` + +### Add members to a room + +`$communication->add_members_to_room()` method is used to add an ad-hoc to add members to a room in the communication provider. The user id of each user to be added to +the provider room is also stored in the communication_user table for user mapping with the provider. + +```php +public function add_members_to_room( + array $userids, + bool $queue = true, +); +``` + +This method accepts the following parameters: + +- An array of user ids to be added to the provider room. +- A boolean value to indicate if the task should be added to the queue or run immediately. This is false by default. This is added to ensure the cases where the mapping should be created but the task might not be needed at this point. + +```php +// First initialize the instance, provider is not required here, it will initialize the enabled instance. +$communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $course->id, +); + +// Now add the members. +$communication->add_members_to_room( + userids: $enrolledusers, +); +``` + +### Update the membership of a room + +`$communication->update_room_membership()` method is used to add an ad-hoc to update the membership of a room in the communication provider. +The user mapping for each of the users are also reset to allow task to update the users from the task. + +```php +public function update_room_membership( + array $userids, + bool $queue = true, +); +``` + +This method accepts the same parameters as the `add_members_to_room()` method and the usage is also the same. + +### Remove members from a room + +`$communication->remove_members_from_room()` method is used to add an ad-hoc to remove members from a room in the communication provider. +The users are flagged as deleted in the communication_user table to allow the task to remove the users from the provider room. + +```php +public function remove_members_from_room( + array $userids, + bool $queue = true +); +``` + +This method accepts the same parameters as the `add_members_to_room()` method and the usage is also the same. + +It's also possible to remove all members from a room by using `$communication->remove_all_members_from_room()`. This method does not take any parameters and will remove all users from the room and delete the user mapping found in the `communication_user` table. + +:::caution + +Both `$communication->remove_all_members_from_room()` and `$communication->remove_members_from_room()` will remove users and may delete communication history from the provider itself. + +::: + +### Show the communication room creation status notification + +`$communication->show_communication_room_status_notification()` is a special method to have a UI element to show the status of the room creation. If the room is ready, it will +return the notification as a string. If the room is not ready, it will return pending status. Course have this implemented and shows the status after the communication instance +is configured. Please note, the status notification relies on the creation of room, not the memberships of the room. + +### Communication instance setup using form/configuration page + +The communication API allows to have settings to configure the basic information like room name, selection of provider etc. `$communication->form_definition()` method +is used to get the form definition for the settings form. If the form elements are used in another form to include the communication form elements, `form_definition()` method +will be useful. There is a configuration page (`communication/configure.php`) which can be used to configure the communication instance. Course currently uses this page to set up +communication and its associated information. +It will also be required to use `set_data()` method in order to set the data to the form elements while saving the data. + +```php +public function form_definition( + \MoodleQuickForm $mform, + string $selectdefaultcommunication = processor::PROVIDER_NONE, +); +``` + +This method accepts the following parameters: + +- The moodle quick form object to add the form elements to. +- The default provider to be selected in the form. This is set to none by default. + +For example, we have a form where we want to have the communication settings, we can use the below code to add the form elements to the form. + +```php +class configure_form extends \moodleform { + public function definition() { + $mform = $this->_form; + $communication = \core_communication\api::load_by_instance( + context: $context, + component: 'core_course', + instancetype: 'coursecommunication', + instanceid: $course->id, + ); + $communication->form_definition(mform: $mform); + $this->communication->set_data(instance: $course); + } +} +``` + +## Building a communication plugin + +Communication API also provides a bunch of interfaces for a communication plugin to consume. Every plugin should implement these interfaces according to the features they +support. + +:::info + +Please refer to [Communication plugin](../../plugintypes/communication/index.md) documentation for more details about building a plugin. + +::: diff --git a/versioned_docs/version-5.1/apis/subsystems/editor/index.md b/versioned_docs/version-5.1/apis/subsystems/editor/index.md new file mode 100644 index 0000000000..bdb2afb1f1 --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/editor/index.md @@ -0,0 +1,54 @@ +--- +title: Editor API +tags: [] +documentationDraft: true +--- + +The editor API lets you control Moodle text editors. It can be found in `lib/editorlib.php`. + +:::important + +Normally you do not need to use this API directly because you can include editors as part of a Moodle form, which will automatically set up the editor for you. + +::: + +## How to set up a text editor + +To set up a text editor on an existing HTML text area field: + +- Call function `editors_get_preferred_editor()`, which will return an object of the texteditor class. +- Call function `use_editor()` to enable the editor for the text area. + +For example, assuming there is an HTML text area with id `mytextareaid`: + +```php +$editor = editors_get_preferred_editor(FORMAT_HTML); +$editor->use_editor('mytextareaid'); +``` + +## Editor options + +The use_editor function allows an options array to be supplied. + +### General options + +- `context`: set to the current context object +- `enable_filemanagement`: set false to disable the file management plugin +- `autosave`: set false to disable autosave + +### Atto-specific options + +- `toolbar`: set to override which icons appear on the toolbar (normally it uses the admin setting - this is for special cases for example if you want a minimal editor in a particular plugin). + +The following example will cause atto to show the four buttons indicated. + +```php +$attobuttons = 'style1 = bold, italic' . PHP_EOL . 'list = unorderedlist, orderedlist'; +$editor->use_editor($id, [ + 'context' => $context, + 'autosave' => false, + 'atto:toolbar' => $attobuttons +], [ + 'return_types' => FILE_EXTERNAL, +]); +``` diff --git a/versioned_docs/version-5.1/apis/subsystems/enrol.md b/versioned_docs/version-5.1/apis/subsystems/enrol.md new file mode 100644 index 0000000000..c1044c66a8 --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/enrol.md @@ -0,0 +1,258 @@ +--- +title: Enrolment API +tags: + - Enrolment + - Library +--- + + + +The enrolment API gives access to the enrolment methods and also to [enrolment plugins](../plugintypes/enrol/index.md) instances. + +## Difference between user enrolment and role assignment + +Users enrolled in a course have at least one record in `user_enrolments` table. This table has the relation between courses and users **through an enrolment plugin instance**. However, `user_enrolments` does not contain information about the user role in the course, only information about: + +- **Enrolment plugin instance** +- **Enrolment status** (active or suspended). +- **Enrolment Start and end dates**. + +The specific role assignments are related to the context, not only to course (as activities and other pages can use its own). The specific roles of a user are stored in the `role_assignments` table. This table stores: + +- The **user role id** in the **context** +- The **component item** that assigned the role. In the case of a regular course, the *component* is the name of the enrolment plugin and the *item id* is the specific plugin instance. + +### What is enrolment? + +Enrolled users may fully participate in a course. Active user enrolment allows user to enter course. Only enrolled users may be group members. Grades are stored only for enrolled users. + +### Unenrolment + +Unenrolment is irreversible operation that purges user participation information. Full unenrolment is suitable only if you do not need to preserve all course participation information including user grades. + +### Enrolment status + +Instead of full unenrolment it is usually better to only *suspend* user enrolment. If there are other ways to enter the course (such guest access) it is recommended to remove user roles at the same time. + +Enrolments have two states defined by two constants: + +- `ENROL_USER_ACTIVE` the enrolment is active +- `ENROL_USER_SUSPENDED` the enrolment is suspended + +### Activity participation + +Activity developers decide the enrolment related behaviour of module. + +There are some general guidelines: + +- Only users with active enrolments should receive notifications. +- Activities should display enrolled users with some capability as participants. +- By default only users with active enrolments should be displayed in reports. +- There should be option to display all enrolled users including suspended enrolments. +- For performance reasons invisible participation data should be purged on unenrolment. +- Contributions visible by other participants should be kept after unenrolment (such as forum posts). + +## API functions + +### is_enrolled() + +Use this method to determine if a user is enrolled into a course. This method returns true for students and teachers, but false for administrators and other managers. + +:::caution + +User enrolments can be either active or suspended, suspended users can not enter the course (unless there is some kind of guest access allowed or have `moodle/course:view` capability) and are usually hidden in the UI. + +::: + +```php +function is_enrolled( + context $context, + stdClass $user = null, + string $withcapability = '', + bool $onlyactive = false +) +``` + +Good example is choice module where we have one slot for each participant, people that are not enrolled are not allowed to vote `is_enrolled($context, $USER, 'mod/choice:choose')`. Another example is assignment where users need to be enrolled and have capability to submit assignments `is_enrolled($this->context, $USER, 'mod/assignment:submit')`. + +### get_enrolled_users() + +Returns the list of enrolled users. This method allows to filter the result by capability, pagination or state. + +```php +function get_enrolled_users( + context $context, + string $withcapability = '', + int $groupid = 0, + string $userfields = 'u.*', + ?string $orderby = null, + int $limitfrom = 0, + int $limitnum = 0, + bool $onlyactive = false +) +``` + +
+
+
+### count_enrolled_users()
+
+This method is used to get the total count of enrolments of a context. As `get_enrolled_users` this methods allow several filters like capability, group id or counting only active enrollments.
+
+```php
+function count_enrolled_users(
+ context $context,
+ string $withcapability = '',
+ int $groupid = 0,
+ bool $onlyactive = false
+)
+```
+
+### get_enrolled_sql()
+
+SQL `select from get_enrolled_sql()` is often used for performance reasons as it can be used in joins to get specific information for enrolled users only.
+
+```php
+function get_enrolled_sql(
+ context $context,
+ string $withcapability = '',
+ int $groupid = 0,
+ bool $onlyactive = false,
+ bool $onlysuspended,
+ int $enrolid = 0
+)
+```
+
+### enrol_get_plugin(): enrol_plugin
+
+Returns the enrolment plugin base class with the given name.
+
+View example
+
+
+Get all users who are able to submit an assignment:
+
+```php
+$submissioncandidates = get_enrolled_users($modcontext, 'mod/assign:submit');
+```
+
+
+
+
+
+## Enrolment plugin methods
+
+Once you use `enrol_get_plugin` function to get the enrolment plugin instance, you can use that class to modify the enrolments.
+
+### $enrol_plugin->enrol_user()
+
+Using this method you can enrol a user into a course.
+
+The method takes the following parameters:
+
+- Enrol plugin instance record
+- User id
+- Role id
+- Optional enrolment start and end timestamps
+- Optional enrolment status (ENROL_USER_ACTIVE or ENROL_USER_SUSPENDED)
+- If the enrol must try to recover the previous user enrolment grades (if any)
+
+```php
+$enrolplugin->enrol_user($instance, $user->id, $role->id, $timestart, $timeend, ENROL_USER_ACTIVE);
+```
+
+### $enrol_plugin->unenrol_user()
+
+Unenrol a user from a course enrolment method.
+
+:::note
+
+Other enrolment methods can define other roles to the same user.
+
+:::
+
+The method takes the following parameters:
+
+- Enrol plugin instance record
+- User id
+
+```php
+$enrolplugin->unenrol_user($instance, $user->id);
+```
+
+### $enrol_plugin->update_user_enrol()
+
+Updates a user enrolment **status** and the **start or end dates**.
+
+The method takes the following parameters:
+
+- Enrol plugin instance record
+- User id
+- Optional enrolment start and end timestamps
+- Optional enrolment status (ENROL_USER_ACTIVE or ENROL_USER_SUSPENDED)
+
+```php
+$enrolplugin->update_user_enrol($instance, $user->id, $timestart, $timeend, ENROL_USER_SUSPENDED);
+```
+
+### $enrol_plugin->add_default_instance()
+
+Add a new enrolment instance to a specific course an returns the instance id. This method will create a new instance record in the `enrol` table with the default values.
+
+The method takes the following parameters:
+
+- Course id
+
+```php
+$enrolplugin->add_default_instance($course->id);
+```
+
+### $enrol_plugin->add_custom_instance()
+
+Add a new enrolment instance to a specific course with custom settings an returns the instance id. This method will create a new instance record in the `enrol` table with the specified settings.
+
+The method takes the following parameters:
+
+- Course object
+- Array of instance settings
+
+```php
+$enrolplugin->add_custom_instance($course, $settings);
+```
+
+### $enrol_plugin->delete_instance()
+
+Remove an enrolment instance form a course and invalidate all related user enrolments.
+
+The method takes the following parameters:
+
+- Enrol plugin instance record
+
+```php
+$enrolplugin->delete_instance($instance);
+```
+
+### $enrol_plugin->is_csv_upload_supported()
+
+Checks whether enrolment plugin is supported in CSV course upload. Defaults to false. Override this function in your enrolment plugin if you want it to
+be supported in CSV course upload.
+
+## See also
+
+- [Enrolment plugins](../plugintypes/enrol/index.md)
diff --git a/versioned_docs/version-5.1/apis/subsystems/external/advanced/_category_.json b/versioned_docs/version-5.1/apis/subsystems/external/advanced/_category_.json
new file mode 100644
index 0000000000..626044609c
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/external/advanced/_category_.json
@@ -0,0 +1,6 @@
+{
+ "position": 6,
+ "label": "Advanced topics",
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/versioned_docs/version-5.1/apis/subsystems/external/advanced/custom-services.md b/versioned_docs/version-5.1/apis/subsystems/external/advanced/custom-services.md
new file mode 100644
index 0000000000..ac5ba42363
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/external/advanced/custom-services.md
@@ -0,0 +1,71 @@
+---
+title: Service creation
+tags:
+ - Web Services
+ - core_external
+ - external
+ - API
+---
+
+Moodle comes with two built-in services that your functions can be attached to.
+
+In rare situations, you may need to create a create a _custom_ service declaration.
+
+The recommended way of creating a new _service_ declaration is by placing it into the `db/services.php` file as a new service declaration.
+
+Moodle Administrators can also manually create a service declaration using the web interface.
+
+This is an advanced feature and, in most cases, _you will not need to use this feature_.
+
+:::note
+
+Whilst writing a service declaration is _optional_, if you do not create a service declaration, then the Moodle administrator will have to create one manually through the Web UI.
+
+If you define a web service here, then the administrator cannot add or remove any function from it.
+
+:::
+
+## Declaring a custom service declaration
+
+Service declarations should be placed in the `db/services.php` file of your plugin (after function declaration), for example `local/groupmanager/db/services.php`.
+
+```php title="local/groupmanager/db/services.php"
+$services = [
+ // The name of the service.
+ // This does not need to include the component name.
+ 'myintegration' => [
+
+ // A list of external functions available in this service.
+ 'functions' => [
+ 'local_groupmanager_create_groups',
+ ],
+
+ // If set, the external service user will need this capability to access
+ // any function of this service.
+ // For example: 'local_groupmanager/integration:access'
+ 'requiredcapability' => 'local_groupmanager/integration:access',
+
+ // If enabled, the Moodle administrator must link a user to this service from the Web UI.
+ 'restrictedusers' => 0,
+
+ // Whether the service is enabled by default or not.
+ 'enabled' => 1,
+
+ // This field os optional, but requried if the `restrictedusers` value is
+ // set, so as to allow configuration via the Web UI.
+ 'shortname' => '',
+
+ // Whether to allow file downloads.
+ 'downloadfiles' => 0,
+
+ // Whether to allow file uploads.
+ 'uploadfiles' => 0,
+ ]
+];
+```
+
+:::note
+
+It is not possible for an administrator to add/remove any function from a pre-built service.
+
+:::
diff --git a/versioned_docs/version-5.1/apis/subsystems/external/description.md b/versioned_docs/version-5.1/apis/subsystems/external/description.md
new file mode 100644
index 0000000000..5d0a6cba74
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/external/description.md
@@ -0,0 +1,85 @@
+---
+title: Function Declarations
+tags:
+ - Web Services
+ - core_external
+ - external
+ - API
+sidebar_position: 1
+---
+
+Before they can be used, all functions must be _declared_ to Moodle, and their inputs and outputs must be _defined_.
+
+- Functions are _declared_ by noting them in the `db/services.php` file for a plugin.
+- Functions are _defined_ within their own class located within the `\component\external` namespace of a component.
+
+Note that there is a strict [naming convention for external service functions](https://moodledev.io/general/development/policies/naming#web-services).
+
+Function implementation classes consist of one class containing a number of functions, some of which are mandatory.
+
+During a Moodle installation or upgrade, the service and function _declarations_ are parsed by a service discovery process and stored within the database. An administrative UI may be used to change _some_ configuration details of these declarations.
+
+## Service declarations
+
+Each component wishing to create an external service function must declare that the function exists by describing it in the `db/services.php` file for that component.
+
+This information is stored internally within Moodle, and collected as part of the service discovery during installation and upgrade.
+
+```php title="local/groupmanager/db/services.php"
+$functions = [
+ // The name of your web service function, as discussed above.
+ 'local_myplugin_create_groups' => [
+ // The name of the namespaced class that the function is located in.
+ 'classname' => 'local_groupmanager\external\create_groups',
+
+ // A brief, human-readable, description of the web service function.
+ 'description' => 'Creates new groups.',
+
+ // Options include read, and write.
+ 'type' => 'write',
+
+ // Whether the service is available for use in AJAX calls from the web.
+ 'ajax' => true,
+
+ // An optional list of services where the function will be included.
+ 'services' => [
+ // A standard Moodle install includes one default service:
+ // - MOODLE_OFFICIAL_MOBILE_SERVICE.
+ // Specifying this service means that your function will be available for
+ // use in the Moodle Mobile App.
+ MOODLE_OFFICIAL_MOBILE_SERVICE,
+ ],
+ ],
+];
+```
+
+View example
+
+
+```php
+$instance = $DB->get_record('enrol', ['courseid' => $course->id, 'enrol' => 'manual'])
+$enrolplugin = enrol_get_plugin($instance->enrol);
+$enrolplugin->enrol_user($instance, $user->id, $role->id, $timestart, $timeend);
+```
+
+:::note
+
+As can be seen in the example, to use the plugin enrol_user and unenrol_user methods you need to get the instance record of the plugin first.
+
+:::
+
+
+
+
+
+The function name is arbitrary, but must follow [the naming convention](https://docs.moodle.org/dev/Web_service_API_functions#Naming_convention). This helps ensure that it is globally unique.
diff --git a/versioned_docs/version-5.1/apis/subsystems/external/files.md b/versioned_docs/version-5.1/apis/subsystems/external/files.md
new file mode 100644
index 0000000000..13efbe516a
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/external/files.md
@@ -0,0 +1,137 @@
+---
+title: File handling
+tags:
+ - Web Services
+ - core_external
+ - external
+ - core_files
+sidebar_position: 4
+---
+
+Moodle provides two ways to fetch and upload files:
+
+1. A set of web service functions; and
+2. A pair of dedicated endpoints.
+
+## Web service functions
+
+You can use the following functions to upload, and fetch, file content:
+
+1. `core_files_get_files()`; and
+1. `core_files_upload()`.
+
+When using these functions, the file content is base64-encoded.
+
+:::note
+
+Many devices do not have enough memory to encode and decode requests containing large files. As such we recommend using the dedicated endpoints instead.
+
+:::
+
+## Dedicated endpoints
+
+Moodle provides two dedicated endpoints which can be used, alongside the authentication token, to upload and fetch content. These are:
+
+- to upload a file: `/webservice/upload.php`; and
+- to fetch a file: `/webservice/pluginfile.php`.
+
+### File upload
+
+The recommended way to upload file content from an external service is by issue a `POST` request to the `/webservice/upload.php` endpoint, passing in a valid web service token for authentication.
+
+Upon successful upload, any files passed will be saved in the user's draft file area.
+
+The endpoint takes two optional arguments:
+
+- An `itemid` to upload the files to, defaulting to `0`. If none is specified then a new id is generated for the current user's draft file area
+- A `filepath` to store the file in, defaulting to `/`.
+
+The endpoint will return a JSON-encoded summary of the uploaded file, including the `itemid` that it was stored in.
+
+:::tip
+
+It is typical that the `itemid` parameter will be used when the files are uploaded singularly in separate HTTP calls and the files are required to be in the same draft file area.
+
+The client retrieves the `itemid` from the first uploaded file and uses it in subsequent uploads.
+
+This allows multiple files to be uploaded to the same draft file area.
+
+:::
+
+On every successful upload, the file/s information are returned in JSON format. If an error occurs, an error message will be sent back in JSON format too.
+
+:::note Example
+
+To upload a file, `users.csv`, you could use curl as follows:
+
+```bash
+$ curl -X POST -F "file_1=@users.csv" https://SITENAME/webservice/upload.php?token=TOKEN \
+| jq
+
+[
+ {
+ "component": "user",
+ "contextid": 567,
+ "userid": "123",
+ "filearea": "draft",
+ "filename": "users.csv",
+ "filepath": "/",
+ "itemid": 880413555,
+ "license": "allrightsreserved",
+ "author": "User User",
+ "source": "O:8:\"stdClass\":1:{s:6:\"source\";s:13:\"users.csv\";}"
+ }
+]
+```
+
+The returned JSON response includes the key parts of the file record, including the `itemid`.
+
+:::
+
+Once all the files are uploaded, you can call a webserivce function to process the files from the user drafts area, passing in the `itemid` of the draft area containing the list of files for the request. The service can identify the uploads and manipulate them as necessary.
+
+An example of a webservice that accepts files is: `mod_assign_save_submission`.
+
+To accept file uploads, the service must allow "files download" (*Administration > Plugins > Web services > Manage services > Edit service > Advanced button*)
+
+## File download
+
+We serve the files through `/webservice/pluginfile.php`. This script requires a web service token for authentication.
+
+To support file downloads, the service must allow "files download".
+
+:::note
+
+The `/webservice/pluginfile.php` endpoint has the exact same structure as `/pluginfile.php` and `/tokenpluginfile.php`.
+
+We don't serve the files through `/pluginfile.php` for web service clients because it requires the user's login session to work, however it is possible to use the `/tokenpluginfile.php` endpoint with an appropriate token.
+
+:::
+
+## Returning files in Web Services
+
+Since Moodle 3.2, you can return a complete file area list via Web Services using the static `get_area_files` method, defined in `external_util`.
+
+```php
+$forum->introfiles = external_util::get_area_files($context->id, 'mod_forum', 'intro', false, false);
+```
+
+You can also use the `external_files` structure definition in combination with the method to return the most common file fields required by WS clients.
+
+```php
+public static function execute_returns(): external_multiple_structure {
+ return new external_multiple_structure(
+ new external_single_structure([
+ 'id' => new external_value(PARAM_INT, 'Forum id'),
+ // ...
+ 'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),
+ // ...
+ ])
+ );
+}
+```
+
+## See also
+
+- [Web services developer documentation](./index.md)
+- [Web services user documentation](https://docs.moodle.org/en/Web_services)
diff --git a/versioned_docs/version-5.1/apis/subsystems/external/functions.md b/versioned_docs/version-5.1/apis/subsystems/external/functions.md
new file mode 100644
index 0000000000..f59dc32c82
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/external/functions.md
@@ -0,0 +1,137 @@
+---
+title: Function Definitions
+tags:
+ - Web Services
+ - API
+ - core_external
+ - external
+sidebar_position: 2
+---
+
+An External function _definition_ is the class, and collection of functions, used to define:
+
+- any parameters that the function expects to take, including any types
+- what the function will return, including any types
+- whether the function has been deprecated, or not
+
+It also includes the code that will actually be executed by the function.
+
+The function definition should be located within the `external` namespace of a component.
+
+:::info Example
+
+For a component named `local_groupmanager` located in `local/groupmanager` which is responsible for creating groups on request, you may have:
+
+- a Web service function named: `local_groupmanager_create_groups`
+- defined in a class named `local_groupmanager\external\create_groups`
+- which is located `local/groupmanager/classes/external/create_groups.php`
+
+:::
+
+A service definition:
+
+- _must_ extend the `\core_external\external_api` class
+- _must_ declare an `execute_parameters` function to describe the expected parameters of the function
+- _must_ declare an `execute` function which is called with the functions and performs the expected actions
+- _must_ declare an `execute_returns` function to describe the values returned by the function
+- _may_ declare an `execute_is_deprecated` function to declare a function as deprecated
+
+Advanced options
+ +A number of advanced options are also available, as described below: + +```php title="local/groupmanager/db/services.php" +$functions = [ + // The name of your web service function, as discussed above. + 'local_myplugin_create_groups' => [ + // A comma-separated list of capabilities used by the function. + // This is advisory only and used to indicate to the administrator + // configuring a custom service definition. + 'capabilities' => 'moodle/course:creategroups,moodle/course:managegroups', + + // The following parameters are also available, but are no longer recommended. + + // The name of the external function name. + // If not specified, this will default to 'execute'. + 'methodname' => 'execute', + + // The file containing the class/external function. + // Do not use if using namespaced auto-loading classes. + 'classpath' => 'local/groupmanager/externallib.php', + ], +]; +``` + +Username and Password + Login Endpoint ->> Client: Session token + Client ->> Protocol Server: Function and authentication token + Protocol Server -->> External API: Access Control Check + Note right of Protocol Server: The Session token is
used to confirm
user permission against
the specified API. + External API -->> Protocol Server: Authentication granted + Protocol Server ->> Plugin API: Function called against
relevant API + Plugin API ->> Protocol Server: Result passed back to Protocol server + Protocol Server -->> External API: Return value validated + Protocol Server ->> Client: Validated data returned to Client +``` + +## Developer documentation + +The External Service API has two categories of documentation: + +1. this documentation details how to _write_ a web service and use the External API; and +2. API documentation for a live Moodle site, which can be found under ** Site administration > Server > Web services > API Documentation **. + +In addition to the standard API endpoints, several additional API endpoints are available for the purpose of uploading, and downloading, files. For more information on these endpoints, see the [file handling](./files.md) documentation. + +- [How to contribute a web service function to core](https://docs.moodle.org/dev/How_to_contribute_a_web_service_function_to_core) +- [Adding a web service to your plugin](./writing-a-service.md) +- Code example: [Adding a web service, using APIs](https://gist.github.com/timhunt/51987ad386faca61fe013904c242e9b4) by (Tim Hunt) +- [Implement a web service client](https://docs.moodle.org/dev/Creating_a_web_service_client) +- [Web services files handling](./files.md) +- [Web service Listing & Roadmap](https://docs.moodle.org/dev/Web_services_Roadmap) + +## Specification and brainstorming + +- [External services security](./security.md) +- [External services description](./description.md) + +## See also + +- [Web service API functions](https://docs.moodle.org/dev/Web_service_API_functions) +- [Web services FAQ](https://docs.moodle.org/en/Web_services_FAQ) +- [How to create and enable a web service](https://docs.moodle.org/en/How_to_create_and_enable_a_web_service) +- [How to enable the mobile web service](https://docs.moodle.org/en/Enable_mobile_web_services) +- [Web services user documentation](https://docs.moodle.org/en/Web_services) +- [Mastering Moodle Web Services development](http://www.slideshare.net/juanleyva/mastering-moodle-web-services-development) - Last session of the Hackfest in the MoodleMoot UK 2016 diff --git a/versioned_docs/version-5.1/apis/subsystems/external/security.md b/versioned_docs/version-5.1/apis/subsystems/external/security.md new file mode 100644 index 0000000000..84c00c356d --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/external/security.md @@ -0,0 +1,85 @@ +--- +title: Security +tags: + - Web Services + - core_external + - external + - API +sidebar_position: 3 +--- + +Before operating on any data in an external function, you must ensure that the user: + +- has access to context that the data is located in +- has permission to perform the relevant action + +## Validating function parameters + +Before working with any data provided by a user you **must** validate the parameters against the definitions you have defined. + +To do so you should call the `validate_parameters()` function, passing in the reference to your `execute_parameters()` function, and the complete list of parameters for the function. The function will return the validated and cleaned parameters. + +The `validate_parameters()` function is defined on the `\core_external\external_api` class, and can be called as follows: + +```php title="local/groupmanager/classes/external/create_groups.php" +public static function execute(array $groups): array { + [ + 'groups' => $groups, + ] = self::validate_parameters(self::execute_parameters(), [ + 'groups' => $groups, + ]); + // ... +} +``` + +## Validating access to the Moodle context + +Whenever fetching or updating any data within Moodle using an External function definition, you **must** validate the context that the data exists within. + +To do so you should call the `validate_context()` function, passing the _most specific_ context for the data. + +For example, if you are working with data belonging to a specific activity, you should use the _activity_ context. If you are working with data belonging to a course, you should use the _course_ context. + +If your function operates on multiple contexts (like a list of courses), you must validate each context right before generating any response data related to that context. + +The `validate_context()` function is defined on the `\core_external\external_api` class, and can be called as follows: + +```php title="local/groupmanager/classes/external/create_groups.php" +public static function execute(array $groups): array { + // ... + foreach ($groups as $group) { + $coursecontext = \context_course::instance($group['courseid']); + self::validate_context($coursecontext); + // ... + } +} +``` + +:::tip + +The `validate_context()` function will also configure the correct theme, language, and filters required to render content for the current user. + +::: + +:::caution + +You should not: + +- use the `require_login` function from an external function - this function is reserved for php scripts returning a web page. +- call `$PAGE->set_context()` manually - this will generate warning notices. + +The `validate_context()` function is the only correct way to write external functions. + +::: + +## Ensuring that a user has the appropriate rights + +Once you have confirmed that the provided data is of the correct type, and configured Moodle for the specific context, you should also ensure that all capabilities are checked correctly. + +You can use the standard capability functions, including: + +- `has_capability()` - to check that a user has a single capability +- `has_any_capability()` - to check that a user has any capability in a set +- `has_all_capability()` - to check that a user has all capabilities in a set +- `require_capability()` - to require a single capability +- `require_all_capabilities()` - to require that a user has all capabilities in a set diff --git a/versioned_docs/version-5.1/apis/subsystems/external/testing.md b/versioned_docs/version-5.1/apis/subsystems/external/testing.md new file mode 100644 index 0000000000..02390fbc7c --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/external/testing.md @@ -0,0 +1,126 @@ +--- +title: Unit Testing +tags: + - Unit testing + - Web Services + - external + - core_external + - API +--- + +Unit tests are the best way of checking the behaviour of your external services and can help you to: + +- discover use cases you didn't think about +- understand the feelings and the needs of the web service client developer +- end up with a function usable by everybody, not only by your own client +- reach integration way faster as you joined a proof of validity +- make the QA process a breeze + +Writing unit tests for an external service function is no different to writing unit tests for any other part of Moodle, which is documented in under [PHPUnit](/general/development/tools/phpunit). + +## How to write an external function PHPUnit test + +You should create one unit test testcase for each external service file, and it should be named after the file that it tests. + +For example, if you have written a service function in `[componentfolder]/classes/external/get_fruit.php`, you should write a unit test in `[componentfolder]/tests/external/get_fruit_test.php`. + +```php title="mod/kitchen/tests/external/get_fruit_test.php" +. + +/** + * Unit tests for the get_fruit function of the kitchen. + * + * @package mod_kitchen + * @category external + * @copyright 20XX Your Name + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +namespace mod_kitchen\external; + +defined('MOODLE_INTERNAL') || die(); + +global $CFG; +require_once($CFG->dirroot . '/webservice/tests/helpers.php'); + +class get_fruit_test extends externallib_advanced_testcase { + + /** + * Test the execute function when capabilities are present. + * + * @covers \mod_fruit\external\get_fruit::execute + */ + public function test_capabilities(): void { + $this->resetAfterTest(true); + + $course = $this->getDataGenerator()->create_course(); + $cm = $this->getDataGenerator()->create_module('mod_kitchen', [ + 'course' => $course->id, + ]); + + // Set the required capabilities by the external function + $contextid = context_module::instance($cm->cmid)->id; + $roleid = $this->assignUserCapability('moodle/CAPABILITYNAME', $contextid); + + // Call the external service function. + $returnvalue = get_fruit::execute([ + 'course' => $course->id, + 'cmid' => $cm->id, + ]); + + // We need to execute the return values cleaning process to simulate + // the web service server. + $returnvalue = \core_external\external_api::clean_returnvalue( + get_fruit::execute_returns(), + $returnvalue + ); + + // Assert that there was a response. + // The actual response is tested in other tests. + $this->assertNotNull($returnvalue); + } + + /** + * Test the execute function when capabilities are missing. + * + * @covers \mod_fruit\external\get_fruit::execute + */ + public function test_capabilities_missing(): void { + global $USER; + + $this->resetAfterTest(true); + + $course = $this->getDataGenerator()->create_course(); + $cm = $this->getDataGenerator()->create_module('mod_kitchen', [ + 'course' => $course->id, + ]); + + // Set the required capabilities by the external function + $contextid = context_module::instance($cm->cmid)->id; + $this->unassignUserCapability('moodle/CAPABILITYNAME', $contextid, $roleid); + + $params = [PARAM1, PARAM2, ...]; + + // Call without required capability + $this->expectException(required_capability_exception::class); + get_fruit::execute([ + 'course' => $course->id, + 'cmid' => $cm->id, + ]); + } +} +``` diff --git a/versioned_docs/version-5.1/apis/subsystems/external/writing-a-service.md b/versioned_docs/version-5.1/apis/subsystems/external/writing-a-service.md new file mode 100644 index 0000000000..83c261a82d --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/external/writing-a-service.md @@ -0,0 +1,488 @@ +--- +title: Writing a new service +tags: + - Web Services + - Plugins + - core_external + - external +sidebar_position: 5 +--- + +This documentation covers the creation of a new external service for use in a web service of a fictional local plugin, `local_groupmanager`. + +## Functional specification + +The `local_groupmanager` plugin has a need to create groups within a course and would like to do so using its own web service. + +:::important + +When defining a new service definition, Moodle requires that the name of the definition be in the form: + +```sh +[frankenstyle_component]_[methodname] +``` + +The [naming convention](https://moodledev.io/general/development/policies/naming#web-services) further dictates that the `methodname` component be in the form: + +```sh +[methodname] - The name of the method in the form of [verb]_[noun] +[verb] - Usually one of get, create, delete, update + A similar verb that well describes the action may also be used +[noun] - The object being modified + Usually in Plural form +``` + +::: + +Per the Moodle naming convention for web services the name of the function should be: + +``` +local_groupmanager_create_groups +``` + +### Inputs + +The `local_groupmanager_create_groups` external service definition will take a list of _groups_ as its only parameters. + +### Outputs + +The service will return a list of the created groups, including the `id` element of those groups. + +### Exceptions and failures + +If _any_ group creation fails, the function will throw an exception, and no groups will be created. + +## Technical specification + +- **the core function the external function will call**: `groups_create_group()` from [/group/lib.php](http://github.com/moodle/moodle/tree/main/moodle/group/lib.php). +- **the parameter types**: a list of object. This object are groups, with `id`/`name`/`courseid`. +- **the returned value types**: a list of objects (groups) with their id. +- **the user capabilities to check**: `moodle/course:managegroups` + +## Declare the web service function + +An external function must be declared before it can be used in your plugin. +Function declarations should be placed in the `db/services.php` file of your plugin. For example in our fictitious plugin this would be located in `local/groupmanager/db/services.php`. + +```php +$functions = [ + // The name of your web service function, as discussed above. + 'local_groupmanager_create_groups' => [ + // The name of the namespaced class that the function is located in. + 'classname' => 'local_groupmanager\external\create_groups', + + // A brief, human-readable, description of the web service function. + 'description' => 'Creates new groups.', + + // Options include read, and write. + 'type' => 'write', + + // Whether the service is available for use in AJAX calls from the web. + 'ajax' => true, + + // An optional list of services where the function will be included. + 'services' => [ + // A standard Moodle install includes one default service: + // - MOODLE_OFFICIAL_MOBILE_SERVICE. + // Specifying this service means that your function will be available for + // use in the Moodle Mobile App. + MOODLE_OFFICIAL_MOBILE_SERVICE, + ] + ], +]; +``` + +
+
+
+## Write the external function descriptions
+
+Every web service function is mapped to an external function. External function are described in the [External functions API](./functions.md).
+Each external function is written with two other functions describing the parameters and the return values. These description functions are used by web service servers to:
+
+- validate the web service function parameters
+- validate the web service function returned values
+- build WSDL files or other protocol documents
+
+These two description functions are located in the class declared in `local/groupmanager/db/services.php`.
+
+Thus for the web service function `local_groupmanager_create_groups()`, we should write a class named `create_groups` in the `local_groupmanager\external` namespace.
+
+This will be located in the file `local/groupmanager/classes/external/create_groups.php`. The class will contain:
+
+- `execute(...)`
+- `execute_parameters()`
+- `execute_return()`
+
+### Defining parameters
+
+```php
+ new external_multiple_structure(
+ new external_single_structure([
+ 'courseid' => new external_value(PARAM_INT, 'id of course'),
+ 'name' => new external_value(
+ PARAM_TEXT,
+ 'multilang compatible name, course unique'
+ ),
+ 'description' => new external_value(
+ PARAM_RAW,
+ 'group description text'
+ ),
+ 'enrolmentkey' => new external_value(
+ PARAM_RAW,
+ 'group enrol secret phrase'
+ ),
+ ])
+ )
+ ]);
+ }
+}
+```
+
+A web service function without parameters will have a parameter description function like that:
+
+```php
+/**
+ * Returns description of method parameters
+ * @return external_function_parameters
+ */
+public static function execute_parameters(): external_function_parameters {
+ return new external_function_parameters([
+ // If this function had any parameters, they would be described here.
+ // This example has no parameters, so the array is empty.
+ ]);
+}
+```
+
+A parameter can be described as:
+
+- a list => `external_multiple_structure`
+- an object => `external_single_structure`
+- a primary type => `external_value`
+
+Our `create_groups()` function expects one parameter named `groups`, so we will first write:
+
+```php
+/**
+ * Returns description of method parameters
+ * @return external_function_parameters
+ */
+public static function execute_parameters(): external_function_parameters {
+ return new external_function_parameters([
+ 'groups' => ...
+ ]);
+}
+```
+
+This *groups* parameter is a list of group. So we will write :
+
+```php
+'groups' => new external_multiple_structure(
+ ...
+)
+```
+
+An external_multiple_structure object (list) can be constructed with:
+
+- `external_multiple_structure` (list)
+- `external_single_structure` (object)
+- `external_value` (primary type).
+
+For our function it will be a `external_single_structure`:
+
+```php
+new external_single_structure([
+ 'courseid' => ...,
+ 'name' => ...,
+ 'description' => ...,
+ 'enrolmentkey' => ...,
+])
+```
+
+Thus we obtain :
+
+```php
+'groups' => new external_multiple_structure(
+ new external_single_structure([
+ 'courseid' => ...,
+ 'name' => ...,
+ 'description' => ...,
+ 'enrolmentkey' => ...,
+ ])
+)
+```
+
+Each group values is a *external_value* (primary type):
+
+- `courseid` is an integer
+- `name` is a string (text only, not tag)
+- `description` is a string (can be anything)
+- `enrolmentkey` is also a string (can be anything)
+
+We add them to the description :
+
+```php
+'groups' => new external_multiple_structure(
+ new external_single_structure([
+ // The second argument is a human readable description text.
+ // This text is displayed in the automatically generated documentation.
+ 'courseid' => new external_value(PARAM_INT, 'id of course'),
+ 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
+ 'description' => new external_value(PARAM_RAW, 'group description text'),
+ 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
+ ])
+)
+```
+
+### execute_returns()
+
+It's similar to execute_parameters(), but instead of describing the parameters, it describes the return values.
+
+```php
+public static function execute_returns() {
+ return new external_multiple_structure(
+ new external_single_structure([
+ 'id' => new external_value(PARAM_INT, 'group record id'),
+ 'courseid' => new external_value(PARAM_INT, 'id of course'),
+ 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
+ 'description' => new external_value(PARAM_RAW, 'group description text'),
+ 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
+ ])
+ );
+}
+```
+
+### Required, Optional or Default value
+
+A value can be `VALUE_REQUIRED`, `VALUE_OPTIONAL`, or `VALUE_DEFAULT`. If not mentioned, a value is `VALUE_REQUIRED` by default.
+
+```php
+'yearofstudy' => new external_value(PARAM_INT, 'year of study', VALUE_DEFAULT, 1979),
+```
+
+- `VALUE_REQUIRED` - if the value is not supplied => the server throws an error message
+- `VALUE_OPTIONAL` - if the value is not supplied => the value is ignored. Note that VALUE_OPTIONAL can't be used in top level parameters, it must be used only within array/objects key definition. If you need top level Optional parameters you should use VALUE_DEFAULT instead.
+- `VALUE_DEFAULT` - if the value is not supplied => the default value is used
+
+:::caution
+
+Because some web service protocols are strict about the number and types of arguments - it is not possible to specify an optional parameter as one of the top-most parameters for a function.
+
+Advanced options
+ +A number of advanced options are also available, as described below: + +```php +$functions = [ + // The name of your web service function, as discussed above. + 'local_groupmanager_create_groups' => [ + // A comma-separated list of capabilities used by the function. + // This is advisory only and used to indicate to the administrator configuring a custom service definition. + 'capabilities' => 'moodle/course:creategroups,moodle/course:managegroups', + + // The following parameters are also available, but are no longer recommended. + + // The name of the external function name. + // If not specified, this will default to 'execute'. + // 'methodname' => 'execute', + + // The file containing the class/external function. + // Do not use if using namespaced auto-loading classes. + // 'classpath' => 'local/groupmanager/externallib.php', + ], +]; +``` + +
+
+
+:::
+
+## Getting files from the user
+
+You will typically use the [Forms API](https://docs.moodle.org/dev/Forms_API) to accept files from users. This topic is detailed in more detail in the [Using the File API in Moodle forms](../form/usage/files.md) documentation.
+
+## Common uses of the file API
+
+Although you will usually interact with the File API from other related APIs including the Form, and Repository APIs, you may find that you need to interact with files directly for a range of purposes.
+
+### Create files
+
+There are several ways to created files in the Moodle file store. Each of them
+requires a `fileinfo` record, which is a `stdClass` object containing all of the
+relevant information that cannot be calculated automatically. A file info record
+may look like the following example:
+
+```php title="A sample file info record"
+$fileinfo = [
+ 'contextid' => $context->id, // ID of the context.
+ 'component' => 'mod_mymodule', // Your component name.
+ 'filearea' => 'myarea', // Usually = table name.
+ 'itemid' => 0, // Usually = ID of row in table.
+ 'filepath' => '/', // Any path beginning and ending in /.
+ 'filename' => 'myfile.txt', // Any filename.
+];
+```
+
+#### From a file on disk
+
+If you need to create a file from another file elsewhere on disk, for example a file you have downloaded into a temporary folder, you can use `create_file_from_pathname`.
+
+```php title="Create a file from a file on disk"
+$fs = get_file_storage();
+
+// Create a new file containing the text 'hello world'.
+$fs->create_file_from_pathname($fileinfo, $requestdir . '/helloworld.txt');
+```
+
+#### From a URL
+
+If you need to fetch a file from a downloadable resource and store it straight into the Moodle filestore, you can use the `create_file_from_url()` function:
+
+```php title="Create a file from a file on disk"
+$fs = get_file_storage();
+
+// Create a new file containing the text 'hello world'.
+$fs->create_file_from_url($fileinfo, 'https://example.com/helloworld.txt');
+```
+
+#### From a string
+
+In some cases you may need to create a file from a string that you have generated, or retrieved in some other manner. For example, a string created from a Template, or image data which has been automatically generated.
+
+```php title="Create a file from a string"
+$fs = get_file_storage();
+
+// Create a new file containing the text 'hello world'.
+$fs->create_file_from_string($fileinfo, 'hello world');
+```
+
+#### From another `stored_file`
+
+In some situations you may need to create a new file entry based on an existing file entry. You may need to do this when copying a file between users in a group activity.
+
+```php title="Create a file from an existing file"
+$fs = get_file_storage();
+
+// Create a new file containing the text 'hello world'.
+$fs->create_file_from_storedfile($fileinfo, $existingfile);
+```
+
+### List all files in a particular file area
+
+You may need to fetch a list of all files in a specific file area. You can do this using the `file_storage::get_area_files()` API, which will return array of `stored_file` objects, for example:
+
+```php title="Fetch a list of all files in the file area"
+$fs = get_file_storage();
+
+// Returns an array of `stored_file` instances.
+$files = $fs->get_area_files($contextid, 'mod_myplugin', 'post', $post->id);
+foreach ($files as $file) {
+ // ...
+}
+```
+
+### Access the content of a file
+
+In some rare situations you may need to use the content of a file stored in the file storage API. The easiest way of doing so is using the `get_content(): string` API call:
+
+```php title="Fetch the content of a file"
+// Get file
+$fs = get_file_storage();
+$file = $fs->get_file(...);
+
+// Read contents
+$contents = $file->get_content();
+```
+
+In some situations you may instead need a standard PHP file _handle_ to the file. You can retrieve a file handle resource using the `get_content_file_handle(): resource` API call, for example:
+
+```php title="Fetch a file handle for a file"
+// Get file
+$fs = get_file_storage();
+$file = $fs->get_file(...);
+
+// Read contents
+$fh = $file->get_content_file_handle();
+
+while($line = fgets($fh)) {
+ // ...
+}
+
+fclose($fh);
+```
+
+:::important
+
+You *cannot* write to a file handle fetched using the `get_content_file_handle()` function and you _must_ call `fclose()` on the returned handle when you have finished using it.
+
+:::
+
+### Copy a file in the File Storage API to elsewhere on disk
+
+As the Moodle File Storage API prevents direct access to files on the disk, if you need a local copy of the file on disk, you must copy the file to a different location. You can use the `\stored_file::copy_content_to(string $destination);` function to achieved this, for example:
+
+```php title="Copy a file to disk"
+// Get file
+$fs = get_file_storage();
+$file = $fs->get_file(...);
+
+$requestdir = make_request_directory();
+$file->copy_content_to("{$requestdir}/helloworld.txt");
+```
+
+### Delete file
+
+You can easily remove a file from the File Storage API using the `\stored_file::delete()` function, for example:
+
+```php
+$fs = get_file_storage();
+
+$file = $fs->get_file(...);
+$file->delete();
+```
+
+### Moving and renaming files around
+
+In some instances you may need to move, or copy, files to other parts of the file structure.
+
+If a file is moving within the same context, file area, and item id, then you can use the `rename(string $path, string $filename)` function, for example:
+
+```php title="Move a file within the same file area"
+$file->rename('/newpath/', '/newname.txt');
+```
+
+If a file is to be moved to a different context, file area, or item id then you will need to create a new file from the old record, and then remove the original file, for example:
+
+```php title="Move a file to a different file area"
+$fs = get_file_storage();
+$filerecord = [
+ 'contextid' => $file->get_contextid(),
+ 'component' => $file->get_component(),
+ 'filearea' => 'newfilearea',
+ 'itemid' => 0,
+ 'filepath' => '/newpath/',
+ 'filename' => $file->get_filename(),
+ 'timecreated' => time(),
+ 'timemodified' => time(),
+];
+$fs->create_file_from_storedfile($filerecord, $file);
+
+// Now delete the original file.
+$file->delete();
+```
+
+### Convert between file formats (office documents)
+
+This functionality requires `unoconv` to be installed and configured on the site - so it is not available on all installations.
+
+```php
+$fs = get_file_storage();
+
+// Prepare file record object
+$fileinfo = [
+ 'component' => 'mod_mymodule', // Your component name.
+ 'filearea' => 'myarea', // Usually = table name.
+ 'itemid' => 0, // Usually = ID of row in table.
+ 'contextid' => $context->id, // ID of context.
+ 'filepath' => '/', // Any path beginning and ending in /.
+ 'filename' => 'myfile.txt', // Any filename.
+ ];
+
+// Fetch the file from the database.
+$file = $fs->get_file(
+ $fileinfo['contextid'],
+ $fileinfo['component'],
+ $fileinfo['filearea'],
+ $fileinfo['itemid'],
+ $fileinfo['filepath'],
+ $fileinfo['filename']
+);
+
+// Try and convert it if it exists
+if ($file) {
+ $convertedfile = $fs->get_converted_document($file, 'pdf');
+}
+```
+
+## See also
+
+- [Core APIs](../../../apis.md)
+- [File API internals](./internals.md) how the File API works internally.
+- [Using the File API in Moodle forms](../form/usage/files.md)
+- [Repository API](../../plugintypes/repository/index.md)
diff --git a/versioned_docs/version-5.1/apis/subsystems/files/internals.md b/versioned_docs/version-5.1/apis/subsystems/files/internals.md
new file mode 100644
index 0000000000..8f20d190aa
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/files/internals.md
@@ -0,0 +1,207 @@
+---
+title: File API internals
+tags:
+ - Architecture
+ - File API
+ - Files
+ - Internals
+---
+
+The goals of the File API are to:
+
+- allow files to be stored within Moodle, as part of the content
+- use a consistent and flexible approach for all file handling throughout Moodle
+- give components control over which users can access a file, using capabilities and other local rules
+- make it easy to determine which parts of Moodle use which files, to simplify operations like backup and restore
+- track where files originally came from
+- avoid redundant storage, when the same file is used twice
+- fully support Unicode file names, irrespective of the capabilities of the underlying file system
+- support alternative file systems, including cloud-based APIs
+
+## Overview
+
+The File API is a set of core interfaces to allow the rest of Moodle to store, serve, and manage files. It applies to all files that are part of the Moodle site's content. It is not used for internal files, such as those in the following subdirectories:
+
+- `dataroot`
+- `temp`
+- `lang`
+- `cache`
+- `environment`
+- `filter`
+- `search`
+- `sessions`
+- `upgradelogs`
+
+See the [File API](./index.md) documentation for information on using the File API.
+
+The API can be subdivided into the following parts:
+
+- [*File system*](#file-system) - Low level storage of file content, without access control
+- [*File storage*](#file-storage) - Storage of file metadata
+- [*File serving*](#file-serving) - Handle the retrieval and serving of files from the File storage API, including:
+ - serving the files on request
+ - performing appropriate access checks
+- *File related user interfaces* - Provides the interface for uploading files, including:
+ - Form elements allowing users to select a file using the file picker, and have it stored within Moodle.
+ - UI for users to manage their files, replacing the old course files UI
+- *File browsing API* - Allow code to browse and optionally manipulate the file areas, including:
+ - find information about available files in each area
+ - print links to files
+ - optionally move, rename, copy, delete, and perform other user-facing operations.
+
+## File API internals
+
+### File System
+
+The File System API allows for files to be stored in alternative underlying file systems, for example in an cloud-based API such as [Amazon S3](https://aws.amazon.com/s3). Each file is stored and retrieved using a `contenthash`.
+
+The file content hash is calculated by taking a SHA1 hash of the content of the file. This should be unique enough so as to allow any number of files to be uploaded to the File API without any natural collisions occurring, and allows the File system to store a single copy of a file, no matter how many times that file content is used within user-generated content.
+
+This means Moodle can not store two files with _different_ content and the _same_ SHA1 hash, luckily it is extremely unlikely that this would ever happen. Technically it is also possible to implement reliable collision tests (with some performance cost), though Moodle currently checks for this case using a simple file length check in addition to SHA1 hash.
+
+:::info
+
+The default file system shipped with Moodle stores all files on disk within the `moodledata` sub-directory of `$CFG->dataroot`.
+
+Suppose a file has a content hash of `081371cb102fa559e81993fddc230c79205232ce`, then it will be stored in on disk as `moodledata/filedir/08/13/081371cb102fa559e81993fddc230c79205232ce`.
+
+:::
+
+:::tip Validation of files
+
+As files in the standard disk-based file storage API are named using their SHA1 hash, there is a simple way of validating files have not become corrupted using the 'sha1sum' command available in most GNU/Linux distributions.
+
+Where a file is correct then the filename will match the `sha1sum` of the file. for example:
+
+```console
+ $ cd /moodlepath/moodledata/filedir/1d/df/
+ $ sha1sum 1ddf5b375fcb74929cdd7efda4f47efc61414edf
+ 1ddf5b375fcb74929cdd7efda4f47efc61414edf 1ddf5b375fcb74929cdd7efda4f47efc61414edf
+```
+
+Where a file has become corrupted, these will differ:
+
+```console
+ $ cd /moodlepath/moodledata/filedir/42/32/
+ $ sha1sum 42327aac8ce5741f51f42be298fa63686fe81b7a
+ 9442188152c02f65267103d78167d122c87002cd 42327aac8ce5741f51f42be298fa63686fe81b7a
+```
+
+:::
+
+### File Storage
+
+The File Storage API is provided by the `\file_storage` class, and stores all metadata relating to a file. It interacts with the File System API and the `\stored_file` class to provide all low-level storage functionality.
+
+### Files table
+
+The File system API stores all file records in the `files` database table. This table contains one entry for each usage of a file. Enough information is kept here so that the file can be fully identified and retrieved again if necessary.
+
+If, for example, the same image is used in a user's profile, and a forum post, then there will be two rows in this table, one for each use of the file, and Moodle will treat the two as separate files, even though the file is only stored once on disc.
+
+Entries with a file name of `.`represent directories. Directory entries like this are created automatically when a file is added within them.
+
+:::note
+
+The name `files` is used in the plural form, even though it goes against the [coding guidelines](https://docs.moodle.org/dev/Database) because `file` is a reserved word in some SQL dialects.
+
+:::
+
+## Implementation of basic operations
+
+The low level access API is defined in the `\file_storage` class, which can be obtained using the `get_file_storage()` function, for example:
+
+```php
+$fs = get_file_storage();
+```
+
+Details of common operations are documented in the [File System API](./index.md) documentation
+
+## File serving
+
+The File serving component of the File API deals with serving files to the user. This is typically in the form of browser requests. Moodle has several main files to handle serving of files. These include:
+
+- `draftfile.php` - the script used to serve files in a user's `draft` file area.
+- `pluginfile.php` - the script typically used by a plugin to access content.
+- `tokenpluginfile.php` - the script typically used by a plugin to access content when a user is not logged in. This is usually in situations where a file is referred to in an e-mail or other similar scenario.
+
+It is the plugins responsibility to handle:
+
+- access control
+- optional XSS protection - student submitted files must not be served with normal headers, we have to force download instead; ideally there should be second wwwroot for serving of untrusted files
+- links to these files are constructed on the fly from the relative links stored in database (see [Generating a URL to your files](./index.md#generating-a-url-to-your-files) for further information).
+
+:::important
+
+Each plugin should only ever use the File Storage API to access its __own files__.
+
+:::
+
+## File related user interfaces
+
+Files are typically selected by users and uploaded to Moodle using the File manager, and the file picker.
+
+- The **file manager** is an interface used to view, and delete existing files, and to add new files.
+- The **file picker** is an interface, often accessed using the _file manager_, to select files for upload to Moodle. The file picker makes use of [file repositories](../../plugintypes/repository/index.md).
+
+### Form fields
+
+Moodle defines two form field types as part of the `formslib` integration, these are:
+
+- The `filepicker`; and
+- the `filemanager`.
+
+### Integration with the HTML editor
+
+Each instance of an HTML editor can be told to store related files in a particular file area.
+
+During editing, files are stored in a draft files area in the `user` component. Then when the form is submitted they are moved into the real file area.
+
+## Other issues
+
+### Unicode support in zip format
+
+Zip format is an old standard for compressing files. It was created long before Unicode existed, and Unicode support was only recently added. There are several ways used for encoding of non-ASCII characters in path names, but unfortunately it is not very standardised. Most Windows packers use DOS encoding.
+
+#### Client software
+
+- Windows built-in compression - bundled with Windows, non-standard DOS encoding only
+- WinZip - shareware, Unicode option (since v11.2)
+- TotalCommander - shareware, single byte(DOS) encoding only
+- 7-Zip - free, Unicode or DOS encoding depending on characters used in file name (since v4.58beta)
+- Info-ZIP - free, uses some weird character set conversions
+
+#### PHP extraction
+
+- Info-ZIP binary execution - no Unicode support at all, mangles character sets in file names (depends on OS, see docs), files must be copied to temp directory before compression and after extraction
+- PclZip PHP library - reads single byte encoded names only, problems with random problems and higher memory usage.
+- Zip PHP extension - kind of works in latest PHP versions
+
+#### Large file support
+
+- PHP running under 32bit operating systems does not support files >2GB. This might be a potential problem for larger backups.
+
+#### Tar Alternative
+
+- tar with gzip compression - easy to implement in PHP + zlib extension (PclTar, Tar from PEAR or custom code)
+- no problem with unicode in *nix, Windows again expects DOS encoding :-(
+- seems suitable for backup/restore - yay!
+
+#### Summary
+
+1. added zip processing class that fully hides the underlying library
+1. using single byte encoding "garbage in/garbage out" approach for encoding of files in zip archives; add new `zipencoding` string into lang packs (for example `cp852` DOS charset for Czech locale) and use it during extraction (we might support true unicode later when PHP Zip extension does that)
+
+### Tar packer
+
+In addition to the zip packer, a tar packer is also available. This creates
+archives in a compressed tar format (similar to the file created by `tar -czf example.tar.gz mycontent`).
+
+The packer is currently limited to ASCII filenames and individual files are limited to 8GB each, but unlike zip there is no limit on the total filesize. It uses the old POSIX format and is compatible with GNU tar using default options.
+
+## See also
+
+- [Repository API](../../plugintypes/repository/index.md)
+- [Portfolio API](https://docs.moodle.org/dev/Portfolio_API)
+- [Resource module file API migration](https://docs.moodle.org/dev/Resource_module_file_API_migration)
+- [MDL-14589](https://moodle.atlassian.net/browse/MDL-14589) - File API Meta issue
diff --git a/versioned_docs/version-5.1/apis/subsystems/form/advanced/_category_.yml b/versioned_docs/version-5.1/apis/subsystems/form/advanced/_category_.yml
new file mode 100644
index 0000000000..b640140c1b
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/form/advanced/_category_.yml
@@ -0,0 +1 @@
+label: Advanced features
diff --git a/versioned_docs/version-5.1/apis/subsystems/form/advanced/advanced-elements.md b/versioned_docs/version-5.1/apis/subsystems/form/advanced/advanced-elements.md
new file mode 100644
index 0000000000..423cffea87
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/form/advanced/advanced-elements.md
@@ -0,0 +1,94 @@
+---
+title: Advanced elements
+tags:
+ - core_form
+ - core
+ - Forms API
+ - Advanced
+---
+
+Form elements can be marked as 'advanced'. This has the effect that they are hidden initially.
+
+To control whether an element is advanced, you can use the `setAdvanced` method on the MoodleQuickForm instance and set a specific element as being advanced, for example:
+
+```php title="Marking an element as advanced"
+$mform->addElement(
+ 'select',
+ 'display',
+ get_string('displaymode', 'choice'),
+ $CHOICE_DISPLAY
+);
+$mform->setAdvanced('display');
+```
+
+It is also possible to unset the advanced status of a field - the `setAdvanced` function takes a second, boolean, parameter which defaults to `true`. By passing a `false` value, the element's advanced flag will be removed, for example:
+
+```php title="Marking an element as advanced"
+// Mark a field as not advanced after it was previously marked as advanced.
+$mform->setAdvanced('display', false);
+```
+
+:::warning
+
+You should be careful about marking too many elements as advanced.
+
+For more information on the risks of this, see the advice in [Designing usable forms](/general/development/policies/designing-usable-forms#use-show-moreless-advanced-settings-sparingly).
+
+:::
+
+:::info Location of Show and hide links
+
+Whenever you mark a form element as advanced, then the _Show / hide advanced_ links are shown automatically at relevant points within the form.
+
+The _Show advanced_ and _Hide advanced_ links are currently displayed at the top right of all fieldsets containing advanced controls.
+
+:::
+
+### Setting a name
+
+When adding a header element, the second parameter to `addElement()` is a name field. You should pass a _unique_ name for each header.
+
+If the name is not specified, or is not unique then this can have a range of unintended impacts, including marking multiple sections of the form as advanced. It is strongly encouraged to _always_ name headers.
+
+See an example implementation of this callback for an activity module.
+ +```php title="mod/myplugin/lib.php" +/** + * Serve the files from the myplugin file areas. + * + * @param stdClass $course the course object + * @param stdClass $cm the course module object + * @param stdClass $context the context + * @param string $filearea the name of the file area + * @param array $args extra arguments (itemid, path) + * @param bool $forcedownload whether or not force download + * @param array $options additional options affecting the file serving + * @return bool false if the file not found, just send the file otherwise and do not return anything + */ +function mod_myplugin_pluginfile( + $course, + $cm, + $context, + string $filearea, + array $args, + bool $forcedownload, + array $options = [] +): bool { + global $DB; + + // Check the contextlevel is as expected - if your plugin is a block, this becomes CONTEXT_BLOCK, etc. + if ($context->contextlevel != CONTEXT_MODULE) { + return false; + } + + // Make sure the filearea is one of those used by the plugin. + if ($filearea !== 'expectedfilearea' && $filearea !== 'anotherexpectedfilearea') { + return false; + } + + // Make sure the user is logged in and has access to the module (plugins that are not course modules should leave out the 'cm' part). + require_login($course, true, $cm); + + // Check the relevant capabilities - these may vary depending on the filearea being accessed. + if (!has_capability('mod/myplugin:view', $context)) { + return false; + } + + // The args is an array containing [itemid, path]. + // Fetch the itemid from the path. + $itemid = array_shift($args); + + // The itemid can be used to check access to a record, and ensure that the + // record belongs to the specifeid context. For example: + if ($filearea === 'expectedfilearea') { + $post = $DB->get_record('myplugin_posts', ['id' => $itemid]); + if ($post->myplugin !== $context->instanceid) { + // This post does not belong to the requested context. + return false; + } + + // You may want to perform additional checks here, for example: + // - ensure that if the record relates to a grouped activity, that this + // user has access to it + // - check whether the record is hidden + // - check whether the user is allowed to see the record for some other + // reason. + + // If, for any reason, the user does not hve access, you can return + // false here. + } + + // For a plugin which does not specify the itemid, you may want to use the following to keep your code consistent: + // $itemid = null; + + // Extract the filename / filepath from the $args array. + $filename = array_pop($args); // The last item in the $args array. + if (empty($args)) { + // $args is empty => the path is '/'. + $filepath = '/'; + } else { + // $args contains the remaining elements of the filepath. + $filepath = '/' . implode('/', $args) . '/'; + } + + // Retrieve the file from the Files API. + $fs = get_file_storage(); + $file = $fs->get_file($context->id, 'mod_myplugin', $filearea, $itemid, $filepath, $filename); + if (!$file) { + // The file does not exist. + return false; + } + + // We can now send the file back to the browser - in this case with a cache lifetime of 1 day and no filtering. + send_stored_file($file, DAY_SECS, 0, $forcedownload, $options); +} +``` + +
+
+
+Once the form has been defined it can be instantiated elsewhere in Moodle, for example:
+
+```php title="[path/to/plugin]/myform.php
+
+// Instantiate the myform form from within the plugin.
+$mform = new \plugintype_pluginname\form\myform();
+
+// Form processing and displaying is done here.
+if ($mform->is_cancelled()) {
+ // If there is a cancel element on the form, and it was pressed,
+ // then the `is_cancelled()` function will return true.
+ // You can handle the cancel operation here.
+} else if ($fromform = $mform->get_data()) {
+ // When the form is submitted, and the data is successfully validated,
+ // the `get_data()` function will return the data posted in the 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 anydefault data (if any).
+ $mform->set_data($toform);
+
+ // Display the form.
+ $mform->display();
+}
+```
+
+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.
+
+```php
+class block_yourblock extends block_base {
+ public function init(){
+ $this->title = 'Your Block';
+ }
+
+ public function get_content(){
+ $this->content = (object) [
+ 'text' => '',
+ ];
+
+ $mform = new \plugintype_pluginname\form\myform();
+
+ if ($mform->is_cancelled()) {
+ // If there is a cancel element on the form, and it was pressed,
+ // then the `is_cancelled()` function will return true.
+ // You can handle the cancel operation here.
+ } else if ($fromform = $mform->get_data()) {
+ // When the form is submitted, and the data is successfully validated,
+ // the `get_data()` function will return the data posted in the 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 anydefault data (if any).
+ $mform->set_data($toform);
+
+ // Display the form.
+ $this->content->text = $mform->render();
+ }
+
+ return $this->content;
+ }
+}
+```
+
+## Form elements
+
+Moodle provides a number of basic, and advanced, form elements. These are described in more detail below.
+
+### Basic form elements
+
+1. [button](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#button)
+1. [checkbox](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#checkbox)
+1. [radio](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#radio)
+1. [select](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#select)
+1. [multi-select](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#multi-select)
+1. [password](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#password)
+1. [hidden](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#hidden)
+1. [html](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#html) - div element
+1. [static](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#static) - Display a static text.
+1. [text](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#text)
+1. [textarea](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#textarea)
+1. [header](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements)
+
+### Advanced form elements
+
+
+
+
+
+
+1. [Autocomplete](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete) - A select box that allows you to start typing to narrow the list of options, or search for results.
+1. [advcheckbox](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#advcheckbox) - Advance checkbox
+1. [choicedropdown](./form/fields/choicedropdown) - A dropdown menu where custom information is displayed on each option.
+1. [float](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#float)
+1. [passwordunmask](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#passwordunmask) - A password element with option to show the password in plaintext.
+1. [recaptcha](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#recaptcha)
+1. [selectyesno](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectyesno)
+1. [selectwithlink](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectwithlink)
+1. [date_selector](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_selector)
+1. [date_time_selector](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_time_selector)
+1. [duration](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#duration)
+1. [editor](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#editor)
+1. [filepicker](./usage/files.md#file-picker) - upload single file
+1. [filemanager](./usage/files.md#file-manager) - upload multiple files
+1. [tags](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#tags)
+1. [addGroup](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#addGroup)
+1. [modgrade](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modgrade)
+1. [modvisible](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modvisible)
+1. [choosecoursefile](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#choosecoursefile)
+1. [grading](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#grading)
+1. [questioncategory](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#questioncategory)
+
+### Custom form elements
+
+In addition to the standard form elements, you can register your own custom form elements, for example:
+
+```php
+// Register a custom form element.
+MoodleQuickForm::registerElementType(
+ // The custom element is named `course_competency_rule`.
+ // This is the element name used in the `addElement()` function.
+ 'course_competency_rule',
+
+ // This is where it's definition is defined.
+ // This does not currently support class auto-loading.
+ "$CFG->dirroot/$CFG->admin/tool/lp/classes/course_competency_rule_form_element.php",
+
+ // The class name of the element.
+ 'tool_lp_course_competency_rule_form_element'
+);
+
+// Add an instance of the custom form element to your form.
+$mform->addElement(
+ // The name of the custome lement.
+ 'course_competency_rule',
+ 'competency_rule',
+ get_string('uponcoursemodulecompletion', 'tool_lp'),
+ $options
+);
+```
+
+For a real-life example, see:
+
+- [Custom element definition](https://github.com/moodle/moodle/blob/main/admin/tool/lp/classes/course_competency_rule_form_element.php)
+- [Custom element usage](https://github.com/moodle/moodle/blob/main/admin/tool/lp/lib.php#L157-L161)
+
+## Commonly used functions
+
+### add_action_buttons()
+
+Add the standard 'action' buttons to the form - these are the standard Submit, and Cancel buttons on the form.
+
+```php
+public function add_action_buttons(
+ bool $cancel = true,
+ ?string $submitlabel = null
+);
+```
+
+- The `$cancel` parameter can be used to control whether a cancel button is shown.
+- The `$submitlabel` parameter can be used to set the label for the submit button. The default value comes from the `savechanges` string.
+
+:::important
+
+The `add_action_buttons` function is defined on the `moodleform` class, and not a part of `$this->_form`, for example:
+
+```php
+ public function definition() {
+ // Add your form elements here.
+ $this->_form->addElement(...);
+
+ // When ready, add your action buttons.
+ $this->add_action_buttons();
+ }
+```
+
+:::
+
+### add_sticky_action_buttons()
+
+An example of a form definition
+ +```php title="[path/to/plugin]/classes/form/myform.php" +libdir/formslib.php"); + +class simplehtml_form extends \moodleform { + // Add elements to form. + public function definition() { + // A reference to the form is stored in $this->form. + // A common convention is to store it in a variable, such as `$mform`. + $mform = $this->_form; // Don't forget the underscore! + + // Add elements to your form. + $mform->addElement('text', 'email', get_string('email')); + + // Set type of element. + $mform->setType('email', PARAM_NOTAGS); + + // Default value. + $mform->setDefault('email', 'Please enter email'); + } + + // Custom validation should be added here. + function validation($data, $files) { + return []; + } +} +``` + +
+
+
+## See also
+
+- [Core APIs](../../../apis.md)
+- [lib/formslib.php Usage](./usage/index.md)
+- [lib/formslib.php Form Definition](https://docs.moodle.org/dev/lib/formslib.php_Form_Definition)
+- [Designing usable forms](/general/development/policies/designing-usable-forms)
+- [Fragment](https://docs.moodle.org/dev/Fragment)
+- [MForm Modal](https://docs.moodle.org/dev/MForm_Modal)
diff --git a/versioned_docs/version-5.1/apis/subsystems/form/usage/files.md b/versioned_docs/version-5.1/apis/subsystems/form/usage/files.md
new file mode 100644
index 0000000000..9468d39ed7
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/form/usage/files.md
@@ -0,0 +1,441 @@
+---
+title: Files in Forms
+tags:
+ - Files
+ - Repositories
+---
+
+Files and their metadata are stored within the [File API](../../files/index.md). Each file within the API is associated with:
+
+- a context id;
+- a component;
+- a _file area_; and
+- an optional item id.
+
+This combination acts as a virtual bucket, within which any desired file structure may be used.
+
+A common use case is to allow users to upload file content within a standard Moodle form.
+
+Normally this works as follows:
+
+1. User starts to create, or re-edit an existing item - this may be a forum post, resource, glossary entry, and so on.
+1. User presses some sort of button to browse for new files to attach or embed
+1. User sees our "Choose file..." dialog, which contains one or more repository instances.
+1. User chooses a file, the corresponding [Repository plugin](../../../plugintypes/repository/index.md) takes care of copying the file into a "draft file area" within Moodle
+1. File appears in the text or as an attachment in the form.
+1. When the user hits save, the [File API](../../files/index.md) is invoked to move the file from the draft file area into a permanent file area associated with that data
+
+This document shows you 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) you can use the [File API](../../files/index.md) without involving form elements.
+
+## Form elements
+
+There are three file-related form elements for interacting with users:
+
+1. `filepicker` - a way to specify one file for the case when you want to process the file and throw it away
+1. `filemanager` - a way to attach one or more files as a collection, using the file picker interface
+1. `editor` - a way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
+
+### File picker
+
+The _File picker_ may be used directly to allow a user to upload _one_ file so that it can be processed, and then removed.
+
+Example use-cases include allowing a single file to be uploaded for a purpose such as CSV import, or restoration of a backup.
+
+:::note
+
+A filepicker element does not typically support storing data within the File API.
+
+If you want a file that remains part of the Moodle storage and will reappear when you reopen the form, then you should use a filemanager instead (and restrict it to a single file, if necessary).
+
+:::
+
+#### Using the filepicker element
+
+```php
+$mform->addElement(
+ 'filepicker',
+ 'userfile',
+ get_string('file'),
+ null,
+ [
+ 'maxbytes' => $maxbytes,
+ 'accepted_types' => '*',
+ ]
+);
+```
+
+#### Working with an uploaded file
+
+To get the contents of the uploaded file:
+
+```php
+$content = $mform->get_file_content('userfile');
+```
+
+To get the name of the uploaded file:
+
+```php
+$name = $mform->get_new_filename('userfile');
+```
+
+To save the uploaded file to the server filesystem:
+
+```php
+$success = $mform->save_file('userfile', $fullpath, $override);
+```
+
+:::note
+
+Be wary of this approach if you need to use the file in multiple page requests.
+
+A clustered server installation will need the file to be accessible on any server node.
+
+:::
+
+To store the chosen file in the Moodle file API:
+
+```php
+$storedfile = $mform->save_stored_file('userfile', ...);
+```
+
+### File manager
+
+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.
+
+Examples of the File manager can be found all over Moodle and include the Forum, and Glossary attachments, Course files, and more.
+
+#### Add a file manager element
+
+Example:
+
+```php
+$mform->addElement(
+ 'filemanager',
+ 'attachments',
+ get_string('attachment', 'moodle'),
+ null,
+ [
+ 'subdirs' => 0,
+ 'maxbytes' => $maxbytes,
+ 'areamaxbytes' => 10485760,
+ 'maxfiles' => 50,
+ 'accepted_types' => ['document'],
+ 'return_types' => FILE_INTERNAL | FILE_EXTERNAL,
+ ]
+);
+```
+
+When a user uploads files, these are stored into a _draft_ file area for that user. It is the developers responsibility to then move those files within the File API.
+
+#### Loading existing files into draft area
+
+If you are presenting a form which has previously had data saved to it, for example when editing an existing piece of content, you will need to copy all of the existing files into the draft file area used in the form. This can be achieved using the `file_prepare_draft_area` function, for example:
+
+```php
+// Fetch the entry being edited, or create a placeholder.
+if (empty($id)) {
+ $entry = (object) [
+ 'id' => null,
+ ];
+} else {
+ $entry = $DB->get_records('glossary_entries', ['id' => $id]);
+}
+
+// Get an unused draft itemid which will be used for this form.
+$draftitemid = file_get_submitted_draft_itemid('attachments');
+
+// Copy the existing files which were previously uploaded
+// into the draft area used by this form.
+file_prepare_draft_area(
+ // The $draftitemid is the target location.
+ $draftitemid,
+
+ // The combination of contextid / component / filearea / itemid
+ // form the virtual bucket that files are currently stored in
+ // and will be copied from.
+ $context->id,
+ 'mod_glossary',
+ 'attachment',
+ $entry->id,
+ [
+ 'subdirs' => 0,
+ 'maxbytes' => $maxbytes,
+ 'maxfiles' => 50,
+ ]
+);
+
+// Set the itemid of draft area that the files have been moved to.
+$entry->attachments = $draftitemid;
+$mform->set_data($entry);
+```
+
+#### Store updated set of files
+
+During the processing of the submitted data, the developer handling the form will need to handle storing the files in an appropriate part of the File API.
+
+This can be accomplished using the `file_save_draft_area_files()` function, for example:
+
+```php
+if ($data = $mform->get_data()) {
+ // ... store or update $entry.
+
+ // Now save the files in correct part of the File API.
+ file_save_draft_area_files(
+ // The $data->attachments property contains the itemid of the draft file area.
+ $data->attachments,
+
+ // The combination of contextid / component / filearea / itemid
+ // form the virtual bucket that file are stored in.
+ $context->id,
+ 'mod_glossary',
+ 'attachment',
+ $entry->id,
+
+ [
+ 'subdirs' => 0,
+ 'maxbytes' => $maxbytes,
+ 'maxfiles' => 50,
+ ]
+ );
+}
+```
+
+### Editors
+
+Another common place to handle files is within an HTML editor, such as TinyMCE.
+
+There are two ways of using the editor element in code, the first one is easier but expects some standardised fields. The second method is more low level.
+
+All of the methods share key behaviours:
+
+- When preparing the editor:
+ - You must create a draft file area to store the files while the user is making changes.
+- When using the editor:
+ - Any files referenced use a full URL, for example `https://example.com/pluginfile.php/123/user/icon/456/filedir/filename.png`.
+ - These files are stored in the draft file area.
+- When processing the form submission:
+ - You must process the content so that part of the URL is replaced with a placeholder - usually `@@PLUGINFILE@@`. For example the URL may become `@@PLUGINFILE@@/filedir/filename.png`.
+ - You must pass it through a function to move the files from the draft file area into the correct file area for your code.
+- When displaying the editor content:
+ - You must pass it through `file_rewrite_pluginfile_urls()` to rewrite it back to a servable URL.
+ - You must provide a `pluginfile` function to perform access control checks and serve the file.
+- When fetching existing content for editing:
+ - You must copy it into a new draft file area so that changes can be made.
+ - You must rewrite the `@@PLUGINFILE@@` URL with the new draft file area.
+
+#### Simple use
+
+By creating a series of fields in the database, it is very easy to have standard functions fetch and store the data for this editor. For example, if you wanted to store data in a field called `textfield`, you would need to create fields in the database for:
+
+- `textfield` - where the content is actually stored
+- `textfieldformat` - to store the _format_ of the field
+- `textfieldtrust` (optional) - to store whether the text is trusted
+
+This is then paired with a set of options which are used when adding the Editor for the form, and processing the file content before displaying, and after saving the form, for example:
+
+```php
+$textfieldoptions = [
+ 'trusttext' => true,
+ 'subdirs' => true,
+ 'maxfiles' => $maxfiles,
+ 'maxbytes' => $maxbytes,
+ 'context' => $context,
+];
+```
+
+To add the editor to the form, and process the form data:
+
+1. Add editor `textfield_editor` to moodle form, pass options through custom data in form constructor.
+You should set `$data->id` to null if data not exist yet.
+
+ ```php
+ $mform->addElement(
+ 'editor',
+ 'textfield_editor',
+ get_string('fieldname', 'somemodule'),
+ null,
+ $textfieldoptions
+ );
+ ```
+
+1. Prepare the data - this will ensure that any existing files will be copied to the draft file area, and any existing placeholder is replaced for use in the form.
+
+ ```php
+ $data = file_prepare_standard_editor(
+ // The existing data.
+ $data,
+
+ // The field name in the database.
+ 'textfield',
+
+ // The options.
+ $textfieldoptions,
+
+ // The combination of contextid, component, filearea, and itemid.
+ $context,
+ 'mod_somemodule',
+ 'somearea',
+ $data->id
+ );
+ ```
+
+1. After the form is submitted, process the editor - this will move the files from the draft file area into the persistent storage, and rewrite the URLs to use the placeholder.
+
+ ```php
+ $data = file_postupdate_standard_editor(
+ // The submitted data.
+ $data,
+
+ // The field name in the database.
+ 'textfield',
+
+ // The options.
+ $textfieldoptions,
+
+ // The combination of contextid, component, filearea, and itemid.
+ $context,
+ 'mod_somemodule',
+ 'somearea',
+ $data->id
+ );
+ ```
+
+Real world examples can be found in `mod/glossary/edit.php` and `mod/glossary/comment.php`.
+
+#### Low-level use
+
+If you prefer, you can call the various underlying functions yourself. This is not typically required.
+
+:::caution Important
+
+You must call both the pre-processing, and post-processing, functions to ensure the correct behaviour.
+
+:::
+
+1. detect if the form was already submitted (this usually means that the draft area already exists) - `file_get_submitted_draft_itemid()`
+1. prepare a draft file area for temporary storage of all files attached to the text - `file_prepare_draft_area()`
+1. convert encoded relative links to absolute links - `file_prepare_draft_area()`
+1. create the form and set current data
+1. after submission the changed files must be merged back into original area - `file_save_draft_area_files()`
+1. absolute links have to be replaced by relative links - `file_save_draft_area_files()`
+
+##### Prepare current data - text and files
+
+```php
+if (empty($entry->id)) {
+ $entry = (object) [
+ 'id' => null,
+ 'definition' => '',
+ '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,
+ [
+ 'subdirs' => true),
+ $entry->definition,
+ ]
+);
+$entry->entry = [
+ 'text' => $currenttext,
+ 'format' => $entry->format,
+ 'itemid' => $draftid_editor,
+];
+
+$mform->set_data($entry);
+```
+
+:::note
+
+Multiple files can be stored in the same virtual bucket. They will have different file names and/or file paths within the same item id.
+
+:::
+
+##### Obtain text, format and save draft files
+
+To retrieve editor content, you need to use following code:
+
+```php
+if ($fromform = $mform->get_data()) {
+ // Content of the editor field.
+ $messagetext = $fromform->entry['text'];
+ // Format of the content.
+ $messageformat = $fromform->entry['format'];
+}
+```
+
+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:
+
+```php
+$messagetext = file_save_draft_area_files(
+ // The id of the draft file area.
+ $draftideditor,
+
+ // The combination of contextid / component / filearea / itemid
+ // form the virtual bucket that file are stored in.
+ $context->id,
+ 'mod_glossary',
+ 'entry',
+ $entry->id,
+
+ // The options to pass.
+ [
+ 'subdirs' => true,
+ ],
+
+ // The text received from the form.
+ $messagetext
+);
+```
+
+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.
+
+```php
+$messagetext = file_rewrite_pluginfile_urls(
+ // The content of the text stored in the database.
+ $messagetext,
+ // The pluginfile URL which will serve the request.
+ 'pluginfile.php',
+
+ // The combination of contextid / component / filearea / itemid
+ // form the virtual bucket that file are stored in.
+ $context->id,
+ 'frankenstyle_component',
+ 'filearea',
+ $itemid
+);
+```
+
+### Implement file serving access control
+
+Attachments and embedded images should have the same access control as the text itself. In a majority of cases these files are served using `pluginfile.php`. Access control is defined in the `[componentpath]/lib.php` file, using a function named `[componentname]_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()`.
+
+## See also
+
+- [File API](../../files/index.md)
+- [Using the file API](../../files/index.md)
+- [Repository plugins](../../../plugintypes/repository/index.md)
diff --git a/versioned_docs/version-5.1/apis/subsystems/form/usage/index.md b/versioned_docs/version-5.1/apis/subsystems/form/usage/index.md
new file mode 100644
index 0000000000..cb9d4fc80f
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/form/usage/index.md
@@ -0,0 +1,142 @@
+---
+title: Form Usage
+tags:
+ - core_form
+ - form
+ - core
+ - API
+documentationDraft: true
+---
+
+Moodle's Form API is an extension of the Pear HTML_QuickForm API, which is no longer supported. Some documentation for the upstream library is [available in the PEAR package page](http://pear.php.net/package/HTML_QuickForm), including a [short tutorial](http://pear.php.net/manual/en/package.html.html-quickform.tutorial.php). A [longer tutorial is also available](http://web.archive.org/web/20130630141100/http://www.midnighthax.com/quickform.php), courtesy of the Internet Archive.
+
+Moodle will attempt to provide a more complete tutorial in this documentation where possible.
+
+:::tip
+
+Some good examples of usage of the Forms API can be found at the following locations:
+
+- [Course edit form - definition](https://github.com/moodle/moodle/blob/main/course/edit_form.php)
+- [Course edit form - usage](https://github.com/moodle/moodle/blob/main/course/edit.php)
+
+:::
+
+Whilst much of the API originates in the PEAR package, all interaction with the library should be via the `moodleform` class, which acts as a controlling wrapper to HTML_QuickForm.
+
+## Basic Usage in A Normal Page
+
+Generally the structure of a page with a form on it looks like this:
+
+```php
+// You will process some page parameters at the top here and get the info about
+// what instance of your module and what course you're in etc. Make sure you
+// include hidden variable in your forms which have their defaults set in set_data
+// which pass these variables from page to page.
+
+// Setup $PAGE here.
+
+// Instantiate the form that you defined.
+$mform = new \plugintype_pluginname\form\myform();
+// Default 'action' for form is strip_querystring(qualified_me()).
+
+// Set the initial values, for example the existing data loaded from the database.
+// This is typically an array of name/value pairs that match the
+// names of data elements in the form.
+// You can also use an object.
+$mform->set_data($toform);
+
+if ($mform->is_cancelled()) {
+ // You need this section if you have a cancel button on your form.
+ // You use this section to handle what to do if your user presses the cancel button.
+ // This is often a redirect back to an older page.
+ // NOTE: is_cancelled() should be called before get_data().
+ redirect($returnurl);
+
+} else if ($fromform = $mform->get_data()) {
+ // This branch is where you process validated data.
+
+ // Typically you finish up by redirecting to somewhere where the user
+ // can see what they did.
+ redirect($nexturl);
+}
+
+// If the form was not cancelled, and data was not submitted, then display the form.
+echo $OUTPUT->header();
+$mform->display();
+echo $OUTPUT->footer();
+```
+
+You are encouraged to look at `lib/formslib.php` to see what additional functions and parameters are available. Available functions are well commented.
+
+## Defining Your Form Class
+
+The form class tells us about the structure of the form.
+
+In most cases you can place this in an auto-loadable class, in which case it should be placed in a folder named `form`, for example:
+
+```php title="mod/forum/classes/form/myform.php
+_form->addElement( ... );
+
+ // Add the standard elements.
+ $this->standard_coursemodule_elements();
+
+ // Add the form actions.
+ $this->add_action_buttons();
+ }
+}
+```
diff --git a/versioned_docs/version-5.1/apis/subsystems/group/index.md b/versioned_docs/version-5.1/apis/subsystems/group/index.md
new file mode 100644
index 0000000000..43f62590ff
--- /dev/null
+++ b/versioned_docs/version-5.1/apis/subsystems/group/index.md
@@ -0,0 +1,216 @@
+---
+title: Groups API
+tags:
+ - API
+ - Subsystem
+ - group
+ - grouping
+ - course
+documentationDraft: true
+---
+
+Moodle [Groups](https://docs.moodle.org/en/Groups) are a way of expressing collections of users within a course. They may be defined by the teacher in the course participants page, or created automatically during a bulk user upload (for example, from a text file).
+
+A teacher can choose whether to use, or even to force, the use of groups for an entire course (from within the Course settings page), or for an individual activity (from within the Activity settings).
+
+Groups can be used in different modes:
+
+- None - groups are not used
+- Separate - users can only see and interact with users in their own group
+- Visible - users can see a list of the other groups and, depending on the activity, may be able to interact with them
+
+If enabled at the course level, the group mode will affect how course-wide reporting functions - for example, if a course-wide group mode of "Separate groups" is enabled, this is applied within the gradebook.
+
+Groups may be grouped together into named [Groupings](https://docs.moodle.org/en/Groupings). The course, and individual activities, can be configured to filter the groups shown to those in a specific Grouping. If a user is a member of multiple groups, then only those groups which belong to the selected grouping are shown.
+
+When a course or activity is in the 'Separate' groups mode, only users within that group can interact with, unless they hold the `moodle/site:accessallgroups` capability. By default, this capability is given to users who hold a role with the `editingteacher`, and `manager` archetypes.
+
+Most of these settings are handled by the core groups code and core groups API. If the activity module wants to implement group support, it need only use the Groups API to:
+
+- Find out the current settings for this instance of the activity
+- Show group controls (for example group selection menus) when appropriate
+- Explore memberships and structures of groups
+- Modify it's own interface to hide/show data accordingly
+
+:::note
+
+Groups are typically only relevant to course features such as Activity modules, some blocks and reports.
+
+Some other core subsystems also need to be group-aware.
+
+:::
+
+## Group modes
+
+There are three different group modes, these modes allow for restrictions to be put in place for access and visibility.
+
+- No groups (`NOGROUPS` constant) - The course or activity has no groups.
+- Separate groups (`SEPARATEGROUPS` constant) - Teachers and students can normally only see information relevant to that group.
+- Visible groups (`VISIBLEGROUPS` constant) - Teachers and students are separated into groups but can still see all information.
+
+This is explained in more detail on the [Groups access control](https://docs.moodle.org/dev/Groups_access_control) page.
+
+:::caution
+
+Only groups with `participation` enabled are available for use in Separate and Visible groups mode. This is enabled by default for groups with *Visible to all* or *Visible to members* visibility (See below) but is always disabled for groups with *See own membership* or *Membership is hidden*.
+
+:::
+
+Calling `groups_get_all_groups()` with the `$participationonly` argument set to `true` will only return groups with `participation` enabled. If you are calling this function within an activity plugin, you will usually want to do this unless you have a good reason not to.
+
+## Group visibility
+
+To help protect user privacy, each group has a `visibility` setting, which controls who can see the group and its members. The possible values are defined as `GROUPS_VISIBILITY_*` constants in grouplib.
+
+Users with the `moodle/course:viewhiddengroups` capability can always see all groups, regardless of their visibility.
+Otherwise, the following restrictions apply:
+
+- Visible to all (`GROUPS_VISIBILITY_ALL` constant) - Everyone can see the group and its members. This is the default, and the legacy behaviour for all groups before Moodle 4.2.
+- Visible to members (`GROUPS_VISIBILITY_MEMBERS` constant) - Only members of the group can see the group, and members of the group can see each others' membership of the group.
+- See own membership (`GROUPS_VISIBILITY_OWN` constant) - Only members of the group can see the group, and members **cannot** see each others' membership, only their own.
+- Membership is hidden (`GROUPS_VISIBILITY_NONE` constant) - No-one can see the group or its members.
+
+The core API functions in `groupslib` such as `groups_get_all_groups()` and `groups_get_members()` will respect the group visibility and the current user's permissions, so use these as far as possible when fetching data about groups and their members. The `\core_group\visibility` class also has helper functions to determine whether a user is allowed to see a group, or its members.
+
+## File locations
+
+The Groups API is currently defined in [lib/grouplib.php](https://github.com/moodle/moodle/blob/main/lib/grouplib.php). This contains global functions which have the `groups_` prefix, for example: `groups_get_group()`.
+
+## Examples
+
+### How to find and use the "current" group
+
+This is using an example from the module forums.
+
+```php
+// Get the course module id from a post or get request.
+$id = required_param('id', PARAM_INT);
+
+// Get the course module.
+$cm = get_coursemodule_from_id('forum', $id, 0, false, MUST_EXIST);
+
+// Get the current group id.
+$currentgroupid = groups_get_activity_group($cm);
+// Get the current group name from the group id.
+$currentgroupname = groups_get_group_name($currentgroupid);
+
+// Do as you please with your newly obtained group information.
+```
+
+### How to make sure that the current user can see a given item in your activity
+
+The following example:
+
+- fetches the course module record for the specified forum id
+- checks whether it has a group mode specified (separate or visible groups)
+- fetches the list of possible groups for that activity
+- checks whether the forum discussion is in a valid group
+
+For this example we are going to check to see if groups are active and whether the user has access to the discussion.
+
+```php
+// Get the course module and discussion id from a post or get request.
+$id = required_param('id', PARAM_INT);
+$discussionid = required_param('discussionid', PARAM_INT);
+
+// Get the course module.
+$cm = get_coursemodule_from_id('forum', $id, 0, false, MUST_EXIST);
+
+// Get the group id for this discussion
+$discussiongroup = $DB->get_record('forum_discussions', ['id' => $discussionid], groupid);
+
+// Check access.
+if (groups_get_activity_groupmode($cm)) {
+ $groups = groups_get_activity_allowed_groups($cm);
+} else {
+ $groups = [];
+}
+if (!in_array($discussiongroup->groupid, array_keys($groups))) {
+ print_error('groupnotamember', 'group');
+}
+
+// Continue on with group specific discussion
+```
+
+### How to display a group menu
+
+The following example will display the group selection dropdown using the `groups_print_activity_menu()` function.
+
+This function will show all groups that the user has access to for the current course module.
+
+After making a selection, the user will be redirected to the `$url` provided.
+
+```php
+// Get the course module id from a post or get request
+$id = required_param('id', PARAM_INT);
+
+// Get the course module
+$cm = get_coursemodule_from_id('forum', $id, 0, false, MUST_EXIST);
+
+// Create a moodle_url. A URL is required so that if the user selects a different group, the page can be
+// reloaded with the new groups information.
+$url = new moodle_url('/mod/forum/view.php', ['id' => $cm->id]);
+
+// Print group information (A drop down box will be displayed if the user is a member of more than one group,
+// or has access to all groups).
+groups_print_activity_menu($cm, $url);
+```
+
+### How to get just the groups that the current user can see
+
+The following example will check whether the current user has permission to see hidden groups on a course, and **if they do not**, will apply additional conditions to a query to restrict the results to just those groups they should see.
+
+```php
+$courseid = required_param('courseid', PARAM_INT);
+$sql = "SELECT g.idnumber, gm.*
+ FROM {groups} g
+ JOIN {groups_members} gm ON gm.groupid = g.id
+ WHERE courseid = ?";
+
+$params = [$courseid];
+
+$context = context_course::instance($courseid);
+if (!has_capability('moodle/course:viewhiddengroups', $context)) {
+ // Apply visibility restrictions.
+ [
+ $visibilitywhere,
+ $visibilityparams
+ ] = \core_group\visibility::sql_group_visibility_where($userid);
+ $sql .= " AND " . $visibilitywhere;
+ $params = array_merge($params, $visibilityparams);
+}
+
+$rs = $DB->get_recordset_sql($sql, $params);
+```
+
+:::note
+
+A query like this must join on `group_members` as group visibility is dependant on the user's own memberships.
+
+:::
+
+Example usage
+ +```php +// Instantiate a form to submit. +$form = new qtype_multichoice_edit_form(...); + +// Fetch the data and then mock the submission of that data. +$questiondata = test_question_maker::get_question_data('multichoice', 'single'); +$form->mock_submit($questiondata); + +// The `get_data()` function will return the validated data, plus any defaults. +$actualfromform = $form->get_data(); + +// The resultant data can now be tested against the expected values. +$expectedfromform = test_question_maker::get_question_form_data('multichoice', 'single'); +$this->assertEquals($expectedfromform, $actualfromform); + +// The data can also be saved and tested in the context of the API. +save_question($actualfromform); +$actualquestiondata = question_load_questions(array($actualfromform->id)); +$this->assertEquals($questiondata, $actualquestiondata); +``` + ++In many situations there is not going to be any more to it than that. + +## Ad-hoc Caches + +This is the alternative method of using the cache API.
+It involves creating a cache using just the required params at the time that it is required. It doesn't require that a definition exists making it quicker and easier to use, however it can only use the default settings and is only recommended for insignificant caches (rarely used during operation, never to be mapped or customised, only existing in a single place in code). + +Once a cache object has been retrieved it operates exactly as the same as a cache that has been created for a definition. + +To create an ad-hoc cache you would use the following: + +```php +$cache = cache::make_from_params(cache_store::MODE_APPLICATION, 'mod_myplugin', 'mycache'); +``` + +:::tip + +Don't be lazy, if you don't have a good reason to use an ad-hoc cache you should be spending an extra 5 minutes creating a definition. + +::: + +## The definition + +The above section illustrated how to create a basic definition, specifying just the area name (the key) and the mode for the definition. Those being the two required properties for a definition. + +There are many other options that will let you make the most of the Cache API and will undoubtedly be required when implementing and converting cache solutions to the Cache API. + +The following details the options available to a definition and their defaults if not applied: + +```php +$definitions = [ + // The name of the cache area is the key. The component/plugin will be picked up from the file location. + 'area' => [ + 'mode' => cache_store::MODE_*, + 'simplekeys' => false, + 'simpledata' => false, + 'requireidentifiers' => ['ident1', 'ident2'], + 'requiredataguarantee' => false, + 'requiremultipleidentifiers' => false, + 'requirelockingread' => false, + 'requirelockingwrite' => false, + 'requirelockingbeforewrite' => false, + 'maxsize' => null, + 'overrideclass' => null, + 'overrideclassfile' => null, + 'datasource' => null, + 'datasourcefile' => null, + 'staticacceleration' => false, + 'staticaccelerationsize' => null, + 'ttl' => 0, + 'mappingsonly' => false, + 'invalidationevents' => ['event1', 'event2'], + 'canuselocalstore' => false + 'sharingoptions' => cache_definition::SHARING_DEFAULT, + 'defaultsharing' => cache_definition::SHARING_DEFAULT, + ], +]; +``` + +### Setting requirements + +The definition can specify several requirements for the cache. + +This includes identifiers that must be provided when creating the cache object, that the store guarantees data stored in it will remain there until removed, a store that supports multiple identifiers, and finally read/write locking. + +The options for these are as follows: + +- `simplekeys`: [bool] Set to true if your cache will only use simple keys for its items.
+Simple keys consist of digits, underscores and the 26 chars of the english language. `a-zA-Z0-9_`
+If true the keys won't be hashed before being passed to the cache store for gets/sets/deletes.
It will be better for performance and possible only because we know the keys are safe. +- `simpledata`: [bool] If set to true we know that the data is scalar or array of scalar.
If true, the data values will be stored as they are. Otherwise they will be serialised first. +- `requireidentifiers`: [array] An array of identifiers that must be provided to the cache when it is created. +- `requiredataguarantee`: [bool] If set to true then only stores that can guarantee data will remain available once set will be used. +- `requiremultipleidentifiers`: [bool] If set to true then only stores that support multiple identifiers will be used. +- `requirelockingread`: [bool] If set to true then a lock will be gained before reading from the cache store. It is recommended not to use this setting unless 100% absolutely positively required. +- `requirelockingbeforewrite`:[bool] If set to true then a lock must be gained and held during expensive computation such as the generation of modinfo before writing to the cache store by the calling code. This is to prevent cache stampedes. After gaining the lock code must check to ensure the cache hasn't already been updated by another process. This is so far only used by course `modinfo` application caches presently. + +### Cache modifiers + +You are also to modify the way in which the cache is going to operate when working for your definition. + +By enabling the static option the Cache API will only ever generate a single cache object for your definition on the first request for it, further requests will be returned the original instance + +This greatly speeds up the collecting of a cache object. + +Enabling persistence also enables a static store within the cache object, anything set to the cache, or retrieved from it will be stored in that static array for the life of the request. +This makes the persistence options some of the most powerful. If you know you are going to be using you cache over and over again or if you know you will be making lots of requests for the same items then this will provide a great performance boost. + +Of course the static storage of cache objects and of data is costly in terms of memory and should only be used when actually required, as such it is turned off by default. +As well as persistence you can also set a maximum number of items that the cache should store (not a hard limit, its up to each store) and a time to live (ttl) although both are discouraged as efficient design negates the need for both in most situations. + +- `staticacceleration`: [bool] This setting does two important things. First it tells the cache API to only instantiate the cache structure for this definition once, further requests will be given the original instance.
Second the cache loader will keep an array of the items set and retrieved to the cache during the request.
This has several advantages including better performance without needing to start passing the cache instance between function calls, the downside is that the cache instance + the items used stay within memory.
Consider using this setting when you know that there are going to be many calls to the cache for the same information or when you are converting existing code to the cache and need to access the cache within functions but don't want to add it as an argument to the function. +- `staticaccelerationsize`: [int] This supplements the above setting by limiting the number of items in the caches persistent array of items.
Tweaking this setting lower will allow you to minimise the memory implications above while hopefully still managing to offset calls to the cache store. +- `ttl`: [int] A time to live for the data (in seconds). It is strongly recommended that you don't make use of this and instead try to create an event driven invalidation system (even if the event is just time expiring, better not to rely on `ttl`).
Not all cache stores will support this natively and there are undesired performance impacts if the cache store does not. +- `maxsize`: [int] If set this will be used as the maximum number of entries within the cache store for this definition.
It's important to note that cache stores don't actually have to acknowledge this setting or maintain it as a hard limit. +- `canuselocalstore`: [bool] This setting specifies whether the cache can safely be local to each frontend in a cluster which can avoid latency costs to a shared central cache server. The cache needs to be carefully written for this to be safe. It is conceptually similar to using `$CFG->localcachedir` (can be local) vs `$CFG->cachedir` (must be shared). Look at `purify_html()` in `lib/weblib.php` for an example. + +### Overriding a cache loader + +:::danger + +This is a super advanced feature and should not be done. Ever. Unless you have a very good reason to do so. + +::: + +It allows you to create your own cache loader and have it be used instead of the default cache loader class. The cache object you get back from the make operations will be an instance of this class. + +- `overrideclass`: [string] A class to use as the loader for this cache. This is an advanced setting and will allow the developer of the definition to take 100% control of the caching solution.
Any class used here must inherit the `cache_loader` interface and must extend default cache loader for the mode they are using. +- `overrideclassfile`: [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required. + +### Specifying a data source + +This is a great wee feature, especially if your code is object orientated. + +It allows you to specify a class that must inherit the `cache_data_source` object and will be used to load any information requested from the cache that is not already being stored. + +When the requested key cannot be found in the cache the data source will be asked to load it. The data source will then return the information to the cache, the cache will store it, and it will then return it to the user as a request of their get request. Essentially no get request should ever fail if you have a data source specified. + +- `datasource`: [string] A class to use as the data loader for this definition.
Any class used here must inherit the cache_data_source interface. +- `datasourcefile`: [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required. + +:::note + +In Moodle versions prior to 3.8.6 and 3.9.3, if caching is disabled then *nothing* will be loaded through the data source which is probably not what you expect (rather than the data source being loaded every time but never cached). See also: [MDL-42012](https://moodle.atlassian.net/browse/MDL-42012) + +::: + +### Misc settings + +The following are stand along settings that don't fall into any of the above categories. + +- `invalidationevents`: [array] An array of events that should cause this cache to invalidate some or all of the items within it. Note that these are NOT normal moodle events and predates the [Events API](https://docs.moodle.org/dev/Events_API). Instead these are arbitrary strings which can be used by `cache_helper::purge_by_event('changesincoursecat');` to mark multiple caches as invalid at once without the calling code knowing which caches are affected. +- `mappingsonly`: [bool] If set to true only the mapped cache store(s) will be used and the default mode store will not. This is a super advanced setting and should not be used unless absolutely required. It allows you to avoid the default stores for one reason or another. +- `sharingoptions`: [int] The sharing options that are appropriate for this definition. Should be the sum of the possible options. +- `defaultsharing`: [int] The default sharing option to use. It's highly recommended that you don't set this unless there is a very specific reason not to use the system default. + +## Localized stores for distributed high performance caching + +Most cache definitions are simple in that the code expects to be able to purge the cache, or update it, and for this to be universally available from then on to all code which loads from this cache again. But as you scale up having a single mega shared cache store doesn't work well for a variety of reasons, including extra latency between multiple front ends and the shared cache service, the number of connections the cache server can handle, the cost of IO between services, and depending on the cache definition issues with locking while writing. + +So if you want very high performance caching then you need to write you code so that it can support being distributed, or localized, which means that each front end can have it's own independent cache store. But this architecture means that you have no direct way to communicate from code running in one place to invalidate the caches on all the other front ends. In order to achieve this you need to carefully construct cache keys so that if the content changes then it uses a new cache key, which will of course be a cache miss and then it will regenerate using fresh data. There are multiple ways to achieve this, a couple common example strategies are below. + +### When should you localize? + +Not all caches are good candidates to localize and some can have a detrimental effect if localized for the wrong reasons. + + +### Revision numbers as key suffix + +A simple method is storing a version number somewhere and appending that to your key. This is the most common method used in Moodle, simply store a number somewhere which is globally shared such as in a custom database field, or using `set_config` / `get_config`. + +One small edge case with this approach is you now need to make sure that the incrementing code is atomic, which means you should use a DB transaction, or gain a lock, before bumping the version so you don't get two conflicting changes ending up on the same version with a race condition. However if you are anticipating high turnover rate of the cache you probably have a deeper issue, see 'Fast churning keys' below. + +One potential benefit of a simple version number strategy if your cache misses are very expensive, is that you can check for the presence of a version, and if it doesn't exist it is easy to simply retrieve the previous version and use it in the mean time, while you could generate the new version asynchronously. This is an advanced concept and depends on the use case and has the obvious disadvantage of showing stale data. + +:::info + +An example of this strategy in Moodle is the theme versions cache: https://github.com/moodle/moodle/blob/main/lib/outputlib.php#L88-L100 + +Note this is not actually in MUC but the caching concepts are the same. + +::: + +It works best with a cache store that supports Least Recently Used garbage collection. + +### Revision numbers as value suffix instead of key suffix + +This is conceptually the same as above but has two important differences. Firstly because the key itself is always the same then only a single version of some value will be stored on disk or in memory for any given cache store which makes it much more efficient in terms of storage. But secondly this comes with a higher coding complexity cost because it will no longer be guaranteed to be correct because a local cache could return a hit with a stale version. So if you need it to be correct you will need to parse out the revision from the value and then confirm the revision is correct before using the value. If it is invalid then you need to treat it as a miss and handle that. One way is to rebuild and set it, but this loses the advantage of primary and final caches (see below). A better way is to delete the local cache but not the final cache by passing a second param of false to delete, and then getting the value again which will repopulate the local cache from the shared cache: + +```php + $cache->delete('foo', false); // Delete the primary / local stale version + $cache->get('foo'); // Get the final / shared version (which may also be stale!) +``` + +But this also is imperfect if there are 3 layers of caching, see [MDL-72837](https://moodle.atlassian.net/browse/MDL-72837) for a full discussion and a possible new api to handle this. + +This method is how the course modinfo cache is localized. + +### Using time as a key suffix + +Another common approach is to use a timestamp, this is how some of the core cache numbers work, see `increment_revision_number()` for some examples. This has the benefit of not needing any transaction or locking, but you do run the risk of two processes clashing if they happen to run in the same second. + +It may look like Moodle theme-related caching uses this strategy, but actually if you look at [the code for theme_get_next_revision](https://github.com/moodle/moodle/blob/df0e58adb140f90712bcd3229ad936d3b4bc15d9/lib/outputlib.php#L88), you will see that it is actually guaranteeing to generate a unique new integer which mitigates the clashing mentioned above. It is just making that integer close to current time-stamp, to make it more self-documenting. + +:::info + +https://github.com/moodle/moodle/blob/main/lib/datalib.php#L1131-L1145 + +It works best with a cache store that supports Least Recently Used garbage collection. +::: + +### Content hashes as keys + +A great strategy is to use a digest or hash such as `sha1` / `sha256` of the content stored inside the cache, or in even more advanced scenarios a hash of the dependencies of the content in the cache. This guarantees that the key will be unique, and can be truly distributed without any synchronous communication between the front ends. + +This strategy can work very well when building up large cache items from many smaller cache fragments in a nested tree structure, eg when caching a structure which is built of other cache items, eg 10 chunks of html to get combined into a large chunk to be cached, you would append the 10 hashes of the 10 smaller chunks and then hash that to use as the key for the combined cache item. This means you can mutate a small part of a tree structure and quickly re-generate the whole tree without expensively regenerating all of the other branches and leaves in the tree. + +:::info + +This is known as 'Russian Doll' caching: https://blog.appsignal.com/2018/04/03/russian-doll-caching-in-rails.html + +::: + +This is a very common strategy is many distributed systems, outside of the context of caching, and is conceptually how git works internally which is why commits are a `sha1` hash. + +This strategy works well if you may periodically change back and forth to previous states which will still be present and so be immediate hits without re-warming. It works best with a cache store that supports Least Recently Used garbage collection. + +### Primary and Final caches + +Because HTTP requests are generally assigned randomly or round-robin to front ends, when a cache item version changes you will now effectively have an empty cache on every front end. As you get the same cache item again and again on each front end it will continue to be a cache miss on each local box until they are all warm, which can ironically mean that on average for a fast-changing, but not often requested cache item, your cache hit rate will be very low and much worse than if you had a shared cache. The solution here is to have multiple levels of caches set up, a local cache backed by a shared cache. You do not need to do anything special in the code to support this if your cache is already localizable, the MUC manages this for you, ie if you request a key missing from the local cache it will then request it from the shared cache. If present it will copy it back to the local cache and then return the value. If it is not present in either then your fallback code will generate the item, and it will be written to both cache stores at the same time. + +This is especially important if you are scaling up and down the number of frontends quickly. If you suddenly need more horizontal scale and create a bunch of new front ends with empty caches and no shared cache they will all consume even more resources warming up and loading the shared services such as the database and filesystem. + +A good rule of thumb is to pair similar types of local and shared caches together. For instance, it is very common to store the Moodle string cache in APCu because it is very heavily used, so an in-memory cache is the fastest and is well paired this a shared cache like Redis. `coursemodinfo` on the other hand is often very large so isn't as practical to store in Redis so it is usually cached on disk, so you could have a local file cache (which could often be very fast `SSD`) and pair it with a shared disk cache in `dataroot` (often much slower over `NFS` or `Gluster`). + +As you scale even bigger, a new bottleneck can appear when purging a shared disk cache ie when you deploy a new version. A full purge needs to iterate over and remove and sync a very large number of files, which can take some time. See [MDL-69088](https://moodle.atlassian.net/browse/MDL-69088) for a proposed fix. + +### Beware fast churning keys + +A big concern when designing a cache is how fast you anticipate it changing. If it contains very fast moving data but sparsely requested data (see above) then you can end up in a situation where you are effectively just using the shared final cache, and wasting latency and space and IO cloning data to the local cache where is may not be hit again very much. As always caching is a balancing act trading off between CPU, time and disk, and ultimately money. + +Even if your cache is able to use a local store that doesn't mean it actually will be configured to be local (and your code can't tell either way). So a wasteful cache item will consume much more space storing all the previous versions of its items even if it isn't localized, and it will be much worse if it is. + +### Time-To-Live for distributed caches + +Another consideration is the total size of your cache stores across all the front ends. As cache keys change they are never be invalidated or purged. So you should have in place some process to garbage collect stale items. This is more a concern for the cache store implementations and the configuration but worth considering. Some stores are deleted on upgrade, or have a Time-To-Live or a Least Recently Used strategy for deleting stale items. + +## Miscellaneous + +- Checkout important [discussion about the Cache API at the Moodle developer chat](https://moodle.org/local/chatlogs/index.php?q=cache) diff --git a/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humandate_example.png b/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humandate_example.png new file mode 100644 index 0000000000..89b36a3311 Binary files /dev/null and b/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humandate_example.png differ diff --git a/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humantimeperiod_example.png b/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humantimeperiod_example.png new file mode 100644 index 0000000000..2f92eb67b6 Binary files /dev/null and b/versioned_docs/version-5.1/apis/subsystems/output/_humandate/humantimeperiod_example.png differ diff --git a/versioned_docs/version-5.1/apis/subsystems/output/_inplace/inplace_editable_example.png b/versioned_docs/version-5.1/apis/subsystems/output/_inplace/inplace_editable_example.png new file mode 100644 index 0000000000..e276ade2fa Binary files /dev/null and b/versioned_docs/version-5.1/apis/subsystems/output/_inplace/inplace_editable_example.png differ diff --git a/versioned_docs/version-5.1/apis/subsystems/output/humandate.md b/versioned_docs/version-5.1/apis/subsystems/output/humandate.md new file mode 100644 index 0000000000..d5efbd1e5b --- /dev/null +++ b/versioned_docs/version-5.1/apis/subsystems/output/humandate.md @@ -0,0 +1,77 @@ +--- +title: Date and Time Output Classes +tags: + - Output +--- + +
+
+```
+
+This is the mustache template for this demo. It uses some bootstrap classes directly to position and style the content on the page. `{{sometext}}` is replaced with the variable from the context when this template is rendered. For more information on templates see [Templates](../../../guides/templates/index.md).
+
+## Output Functions
+
+This section explains how dynamic data should be sent from Moodle to the web browser in an organised and standard way.
+
+:::important
+It is possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.
+
+By using them you will be helping to have better, more secure and readable code. Spend some minutes trying to understand them, please!
+:::
+
+Of course, these functions can be discussed, modified and new functions can arrive if there are some good reasons for it. Just discuss it in the [General developer forum](http://moodle.org/mod/forum/view.php?id=55).
+
+For each of the functions below we'll try to explain when they should be used, explaining the most important parameters supported and their meaning. Let's review them!
+
+### String formatting functions
+
+The `format_string` and `format_text` functions should always be used when preparing the output of information. They may also be used to process information before it is stored in the database however, filters should only be applied at output. For example, language filters must only be applied as the content is prepared for output because we don't yet know the user's preferred language.
+
+#### p() and s()
+
+```php
+function s($var, $strip=false)
+function p($var, $strip=false)
+```
+
+The only difference between these two functions is that `s()` returns the string, while `p()` prints it directly.
+
+These functions should be used to:
+
+- Print all the **values of form fields** like `` or `Heading
+{{sometext}}
+