MoodleDocs - User contributions [en]

Moodle App Plugins Development Guide

2022-04-25T07:54:59Z

Dpalou: 4.0 app now automatically creates two link handlers for module plugins.

{{Moodle App (Ionic 5)}}
If you want to add mobile support to your Moodle plugin, you can achieve it by extending different areas of the app using ''just PHP server side code'' and providing templates written with [https://ionicframework.com/docs/components Ionic] and custom components.

You will have to:
# Create a <code>db/mobile.php</code> file in your plugin. In this file, you will be able to indicate which areas of the app you want to extend. For example, adding a new option in the main menu, implementing support for a new activity module, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered as html. This html should use Ionic components so that it looks native, but it can be generated using mustache templates.

Let’s clarify some points:
* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function <code>tool_mobile_get_content</code>.
* As arguments of your functions you will always receive the <code>userid</code>, some relevant details of the app (like the app version or the current language in the app), and some specific data depending on the type of plugin (<code>courseid</code>, <code>cmid</code>, ...).
* The mobile app also implements a list of custom Ionic components and directives that provide dynamic behaviour; like indicating that you are linking a file that can be downloaded, allowing a transition to new pages into the app calling a specific function in the server, submitting form data to the server, etc.

==Getting started==
If you only want to write a plugin, it is not necessary that you set up your environment to work with the Moodle App. In fact, you don't even need to compile it. You can just [[Using the Moodle App in a browser|use a Chromium-based browser]] to add mobile support to your plugins!

You can use the app from one of the hosted versions on [https://master.apps.moodledemo.net master.apps.moodledemo.net] (the latest stable version) and [https://integration.apps.moodledemo.net integration.apps.moodledemo.net] (the latest development version). If you need any specific environment (hosted versions are deployed with a ''production'' environment), you can also use [[Moodle App Docker Images|Docker images]]. And if you need to test your plugin in a native device, you can always use [https://download.moodle.org/mobile Moodle HQ's application].

This should suffice for developing plugins. However, if you are working on advanced functionality and you need to run the application from the source code, you can find more information in the [[Moodle App Development Guide]].
===Development workflow===
Before getting into the specifics of your plugin, we recommend that you start adding a simple "Hello World" button in the app to see that everything works properly.

Let's say your plugin is called <code>local_hello</code>, you can start by adding the following files:

<code>db/mobile.php</code>
<syntaxhighlight lang="php">
<?php

$addons = [
'local_hello' => [
'handlers' => [
'hello' => [
'delegate' => 'CoreMainMenuDelegate',
'method' => 'view_hello',
'displaydata' => [
'title' => 'hello',
'icon' => 'earth',
],
],
],
'lang' => [
['hello', 'local_hello'],
],
],
];
</syntaxhighlight>
<code>classes/output/mobile.php</code>
<syntaxhighlight lang="php">
<?php

namespace local_hello\output;

defined('MOODLE_INTERNAL') || die();

class mobile {

public static function view_hello() {
return [
'templates' => [
[
'id' => 'main',
'html' => '<h1 class="text-center">{{ "plugin.local_hello.hello" | translate }}</h1>',
],
],
];
}

}
</syntaxhighlight>
<code>lang/en/local_hello.php</code>
<syntaxhighlight lang="php">
<?php

$string['hello'] = 'Hello World';
</syntaxhighlight>
Once you've done that, try logging into your site in the app and you should see a new button in the main menu or more menu (depending on the device) saying "Hello World". If you press this button, you should see a page saying "Hello World!".

Congratualtions, you have written your first Moodle plugin with moodle support!

You can read the rest of this page to learn more about mobile plugins and start working on your plugin. Here's some things to keep in mind:
* If you change the <code>mobile.php</code> file, you will have to refresh the browser. And remember to [https://developer.chrome.com/docs/devtools/network/reference/#disable-cache disable the network cache].
* If you change an existing template or function, you won’t have to refresh the browser. In most cases, doing a PTR (Pull To Refresh) in the page that displays the template will suffice.
* If any of these doesn't show your changes, you may need to [https://docs.moodle.org/311/en/Developer_tools#Purge_all_caches purge all caches] to avoid problems with the auto-loading cache.
* Ultimately, if that doesn't work either, you may have to log out from the site and log in again. If any changes affect plugin installation, you may also need to increase the version in your plugin's <code>version.php</code> file and upgrade it in the site.
==Types of plugins==
There are 3 types of plugins:
===Templates generated and downloaded when the user opens the plugins===
[[File:Templates_downloaded_when_requested.png|thumb]]
With this type of plugin, the template of your plugin will be generated and downloaded when the user opens the plugin in the app. This means that your function will receive some context parameters. For example, if you're developing a course module plugin you will receive the <code>courseid</code> and the <code>cmid</code> (course module ID). You can see the list of delegates that support this type of plugin in the [[#Delegates|Delegates]] section.
===Templates downloaded on login and rendered using JS data===
[[File:Templates_downloaded_on_login.png|thumb]]
With this type of plugin, the template for your plugin will be downloaded when the user logs in into the app and will be stored in the device. This means that your function will not receive any context parameters, and you need to return a generic template that will be built with JS data like the ones in the Moodle App. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[#Delegates|Delegates]] section.
===Pure JavaScript plugins===
You can always implement the whole plugin yourself using JavaScript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[#Delegates|Delegates]] section.
==Step by step example==
In this example, we are going to update an existing plugin, the [https://github.com/mdjnelson/moodle-mod_certificate Certificate activity module], that previously used a [[Moodle Mobile 2 (Ionic 1) Remote add-ons|Remote add-on]] (a legacy approach to implement mobile plugins).

This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.
===Step 1. Update the <code>db/mobile.php</code> file===
In this case, we are updating an existing file. For new plugins, you should create this new file.
<syntaxhighlight lang="php">
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</syntaxhighlight>
;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields). In this case, we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the [[#Delegates|Delegates]] section for all the possible options.

; Method:
: This is the method in the Moodle <code>\{component-name}\output\mobile</code> class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the <code>mobile.php</code> file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current <code>userid</code> (and <code>courseid</code> when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently <code>userid</code> and <code>courseid</code>).
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the <code>files</code> array).
: Note that if your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a <code>page</code> parameter in addition to the usual <code>cmid</code>, <code>courseid</code>, and <code>userid</code>) then the app will not know which additional parameters to supply. In this case, do not list the function in <code>offlinefunctions</code>; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here, like <code>['cancel', 'moodle']</code>. If you do this, be warned that in the app you will then need to refer to that string as <code><nowiki>{{ 'plugin.myplugin.cancel' | translate }}</nowiki></code> (not <code><nowiki>{{ 'plugin.moodle.cancel' | translate }}</nowiki></code>).
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.
There are additional attributes supported by the <code>mobile.php</code> list, you can find about them in the [[#Mobile.php_supported_options|Mobile.php supported options]] section.
===Step 2. Creating the main function===
The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem <code>classes/output</code> directory, the name of the class must be <code>mobile</code>.

For this example, the namespace name will be <code>mod_certificate\output</code>.

<code>mod/certificate/classes/output/mobile.php</code>
<syntaxhighlight lang="php">
<?php

namespace mod_certificate\output;

use context_module;
use mod_certificate_external;

class mobile {

/**
* Returns the certificate course view for the mobile app.
*
* @param array $args Arguments from tool_mobile_get_content WS.
*
* @return array HTML, JS and other data.
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid, false, $cm, true, true);

$context = \context_module::instance($cm->id);

require_capability('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', ['id' => $cm->instance]);

// Get certificates from external (taking care of exceptions).
try {
$issued = \mod_certificate_external::issue_certificate($cm->instance);
$certificates = \mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = [];
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
[$certificate->intro, $certificate->introformat] =
external_format_text($certificate->intro, $certificate->introformat, $context->id, 'mod_certificate', 'intro');
$data = [
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid,
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</syntaxhighlight>
;Function declaration:
: The function name is the same as the one used in the <code>mobile.php</code> file (<code>method</code> field). There is only one argument, <code>$args</code>, which is an array containing all the information sent by the mobile app (the <code>courseid</code>, <code>userid</code>, <code>appid</code>, <code>appversionname</code>, <code>appversioncode</code>, <code>applang</code>, <code>appcustomurlscheme</code>, ...).

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a <code>view.php</code> script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

; Function return:
* <code>templates</code> — The rendered template (notice that we could return more than one template, but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some JavaScript code.
* <code>javascript</code> — Empty, because we don’t need any in this case.
* <code>otherdata</code> — Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way data-binding in the template.
* <code>files</code> — A list of files that the app should be able to download (for offline usage mostly).
===Step 3. Creating the template for the main function===
This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic, together with directives and components specific to the Moodle App.

All the HTML elements starting with <code>ion-</code> are ionic components. Most of the time, the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML elements starting with <code>core-</code> are custom components of the Moodle App.

<code>mod/certificate/templates/mobile_view_page.mustache</code>
<syntaxhighlight lang="html+handlebars">
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>">
</core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<ion-button expand="block" color="light" core-site-plugins-new-content title="<% certificate.name %>"
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</ion-button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<ion-button expand="block" core-course-download-module-main-file moduleId="<% cmid %>"
courseId="<% certificate.course %>" component="mod_certificate"
[files]="[{
fileurl: '<% issue.fileurl %>',
filename: '<% issue.filename %>',
timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>',
}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate"
[params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}">
</span>
</ion-list>
</div>
</syntaxhighlight>
In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code>core-course-module-description</code>, which is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.

The following line using the <code>translate</code> filter indicates that the app will translate the <code>summaryofattempts</code> string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has the following format:
<syntaxhighlight lang="text">
plugin.{plugin-identifier}.{string-id}
</syntaxhighlight>
Where <code>{plugin-identifier}</code> is taken from <code>mobile.php</code> and <code>{string-id}</code> must be indicated in the <code>lang</code> field in <code>mobile.php</code>.

Then, we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the <code>mobile_issues_view</code> function in the <code>mod_certificate</code> component; passing as arguments the <code>cmid</code> and <code>courseid</code>. The content returned by this function will be displayed in a new page (read the following section to see the code of this new page).

Just after this button, we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available offline.

Finally, just before the <code>ion-list</code> is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call a Web Service function in the server, in this case we are calling the <code>mod_certificate_view_certificate</code> that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.
===Step 4. Adding an additional page===
Add the following method to <code>mod/certificate/classes/output/mobile.php</code>:
<syntaxhighlight lang="php">
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS.
*
* @return array HTML, JS and other data.
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid, false, $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', ['id' => $cm->instance]);

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = [];
}

$data = ['issues' => $issues];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</syntaxhighlight>
This method for the new page was added just after <code>mobile_course_view</code>, the code is quite similar: checks the capabilities, retrieves the information required for the template, and returns the template rendered.

The code of the mustache template is also very simple.

<code>mod/certificate/templates/mobile_view_issues.mustache</code>
<syntaxhighlight lang="html+handlebars">
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</syntaxhighlight>
As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an Ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter <code>coreToLocaleString</code>). We are also displaying the grade displayed in the certificate (if any).
===Step 5. Plugin webservices, if included===
If your plugin uses its own web services, they will also need to be enabled for mobile access in your <code>db/services.php</code> file.

The following line should be included in each webservice definition:
<syntaxhighlight lang="php">
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
</syntaxhighlight>
<code>mod/certificate/db/services.php</code>
<syntaxhighlight lang="php">
<?php

$functions = [
'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</syntaxhighlight>
==Mobile.php supported options==
In the previous section, we learned about some of the existing options for handlers configuration. This is the full list of supported options.
===Common options===
* <code>delegate</code> (mandatory) — Name of the delegate to register the handler in.
* <code>method</code> (mandatory) — The method to call to retrieve the main page content.
* <code>init</code> (optional) — A method to call to retrieve the initialisation JS and the restrictions to apply to the whole handler. It can also return templates that can be used from JavaScript. You can learn more about this in the [[#Initialisation|Initialisation]] section.
* <code>restricttocurrentuser</code> (optional) — Only used if the delegate has a <code>isEnabledForUser</code> function. If true, the handler will only be shown for the current user. For more info about displaying the plugin only for certain users, please see [[#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* <code>restricttoenrolledcourses</code> (optional) — Only used if the delegate has a <code>isEnabledForCourse</code> function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* <code>styles</code> (optional) — An array with two properties: <code>url</code> and <code>version</code>. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* <code>moodlecomponent</code> (optional) — If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be <code>local_whatever</code>, but in <code>moodlecomponent</code> you can specify that this handler will implement <code>format_whatever</code> or <code>mod_whatever</code>. This property was introduced in the version 3.6.1 of the app.
===Options only for CoreMainMenuDelegate ===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the More tab, they cannot be displayed as tabs in the bottom bar.
* <code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreMainMenuHomeDelegate ===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
* <code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreCourseOptionsDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
* <code>ismenuhandler</code> (optional) — Supported from the 3.7.1 version of the app. Set it to <code>true</code> if you want your plugin to be displayed in the contextual menu of the course instead of in the top tabs. The contextual menu is displayed when you click in the 3-dots button at the top right of the course.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreCourseModuleDelegate===
* <code>displaydata</code> (mandatory):
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>method</code> (optional) — The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* <code>offlinefunctions</code> (optional) — List of functions to call when prefetching the module. It can be a <code>get_content</code> method or a WS. You can filter the params received by the WS. By default, WS will receive these params: <code>courseid</code>, <code>cmid</code>, <code>userid</code>. Other valid values that will be added if they are present in the list of params: <code>courseids</code> (it will receive a list with the courses the user is enrolled in), <code>{component}id</code> (For example, <code>certificateid</code>).
* <code>downloadbutton</code> (optional) — Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* <code>isresource</code> (optional) — Whether the module is a resource or an activity. Only used if there is any offline function. If your module relies on the <code>contents</code> field, then it should be <code>true</code>.
* <code>updatesnames</code> (optional) — Only used if there is any offline function. A regular expression to check if there's any update in the module. It will be compared to the result of <code>core_course_check_updates</code>.
* <code>displayopeninbrowser</code> (optional) — Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: <code>this.displayOpenInBrowser = false;</code>. Supported from the 3.6 version of the app.
* <code>displaydescription</code> (optional) — Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: <code>this.displayDescription = false;</code>. Supported from the 3.6 version of the app.
* <code>displayrefresh</code> (optional) — Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: <code>this.displayRefresh = false;</code>. Supported from the 3.6 version of the app.
* <code>displayprefetch</code> (optional) — Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: <code>this.displayPrefetch = false;</code>. Supported from the 3.6 version of the app.
* <code>displaysize</code> (optional) — Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: <code>this.displaySize = false;</code>. Supported from the 3.6 version of the app.
* <code>supportedfeatures</code> (optional) — It can be used to specify the supported features of the plugin. Currently the app only uses <code>FEATURE_MOD_ARCHETYPE</code> and <code>FEATURE_NO_VIEW_LINK</code>. It should be an array with features as keys (For example, <code>[FEATURE_NO_VIEW_LINK => true</code>). If you need to calculate this dynamically please see [[#Module_plugins:_dynamically_determine_if_a_feature_is_supported|Module plugins: dynamically determine if a feature is supported]]. Supported from the 3.6 version of the app.
* <code>coursepagemethod</code> (optional) — If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML. Supported from the 3.8 version of the app.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreCourseFormatDelegate===
* <code>canviewallsections</code> (optional) — Whether the course format allows seeing all sections in a single page. Defaults to <code>true</code>.
* <code>displayenabledownload</code> (optional) — Deprecated in the 4.0 app, it's no longer used.
* <code>displaysectionselector</code> (optional) — Deprecated in the 4.0 app, use ''displaycourseindex'' instead.
*<code>displaycourseindex</code> (optional) — Whether the default course index should be displayed. Defaults to <code>true</code>.
===Options only for CoreUserDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>type</code> — The type of the addon. The values accepted are <code>'newpage'</code> (default) and <code>'communication'</code>.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreSettingsDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for AddonMessageOutputDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreBlockDelegate===
* <code>displaydata</code> (optional):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section. If this is not supplied, it will default to <code>'plugins.block_{block-name}.pluginname'</code>, where <code>{block-name}</code> is the name of the block.
** <code>class</code> — A CSS class. If this is not supplied, it will default to <code>block_{block-name}</code>, where <code>{block-name}</code> is the name of the block.
** <code>type</code> — Possible values are:
*** <code>"title"</code> — Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
*** <code>"prerendered"</code> — Your block will display the content and footer returned by the WebService to get the blocks (for example, <code>core_block_get_course_blocks</code>), so your block's method will never be called.
*** Any other value — Your block will immediately call the method specified in <code>mobile.php</code> and it will use the template to render the block.
* <code>fallback</code> (optional) — This option allows you to specify a block to use in the app instead of your block. For example, you can make the app display the "My overview" block instead of your block in the app by setting <code>'fallback' => 'myoverview'</code>. The fallback will only be used if you don't specify a <code>method</code> and the <code>type</code> is different to <code>'title'</code> or <code>'prerendered'</code>. Supported from the 3.9.0 version of the app.
==Delegates==
Delegates can be classified by type of plugin. For more info about type of plugins, please see the [[#Types_of_plugins|Types of plugins]] section.
===Templates generated and downloaded when the user opens the plugins===
====<code>CoreMainMenuDelegate</code>====
You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).
====<code>CoreMainMenuHomeDelegate</code>====
You must use this delegate when you want to add new tabs in the home page (by default the app is displaying the "Dashboard" and "Site home" tabs).
====<code>CoreCourseOptionsDelegate</code>====
You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).
====<code>CoreCourseModuleDelegate</code>====
You must use this delegate for supporting activity modules or resources.
====<code>CoreUserDelegate</code>====
You must use this delegate when you want to add additional options in the user profile page in the app.
====<code>CoreCourseFormatDelegate</code>====
You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a <code>CoreCourseFormatDelegate</code> handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format.

You can learn more about this at the [[Creating mobile course formats]] page.
====<code>CoreSettingsDelegate</code>====
You must use this delegate to add a new option in the settings page.
====<code>AddonMessageOutputDelegate</code>====
You must use this delegate to support a message output plugin.
====<code>CoreBlockDelegate</code>====
You must use this delegate to support a block. For example, blocks can be displayed in Site Home, Dashboard and the Course page.
===Templates downloaded on login and rendered using JS data===
====<code>CoreQuestionDelegate</code>====
You must use this delegate for supporting question types.

You can learn more about this at the [[Creating mobile question types]] page.
====<code>CoreQuestionBehaviourDelegate</code>====
You must use this delegate for supporting question behaviours.
====<code>CoreUserProfileFieldDelegate</code>====
You must use this delegate for supporting user profile fields.
====<code>AddonModQuizAccessRuleDelegate</code>====
You must use this delegate to support a quiz access rule.
====<code>AddonModAssignSubmissionDelegate</code> and <code>AddonModAssignFeedbackDelegate</code>====
You must use these delegates to support assign submission or feedback plugins.
====<code>AddonWorkshopAssessmentStrategyDelegate</code>====
You must use this delegate to support a workshop assessment strategy plugin.
===Pure JavaScript plugins===
These delegates require JavaScript to be supported. See [[#Initialisation|Initialisation]] for more information.
* <code>CoreContentLinksDelegate</code>
* <code>CoreCourseModulePrefetchDelegate</code>
* <code>CoreFileUploaderDelegate</code>
* <code>CorePluginFileDelegate</code>
* <code>CoreFilterDelegate</code>
==Available components and directives==
===Difference between components and directives===
A directive is usually represented as an HTML attribute, allows you to extend a piece of HTML with additional information or functionality. Example of directives are: <code>core-auto-focus</code>, <code>*ngIf</code>, and <code>ng-repeat</code>.

Components are also directives, but they are usually represented as an HTML tag and they are used to add custom elements to the app. Example of components are <code>ion-list</code>, <code>ion-item</code>, and <code>core-search-box</code>.

Components and directives are Angular concepts; you can learn more about them and the components come out of the box with Ionic in the following links:
* [https://angular.io/guide/built-in-directives Angular directives documentation]
* [https://ionicframework.com/docs/components Ionic components]
===Custom core components and directives===
These are some useful custom components and directives that are only available in the Moodle App. Please note that this isn’t the full list of custom components and directives, it’s just an extract of the most common ones.

You can find a full list of components and directives in the source code of the app, within [https://github.com/moodlehq/moodleapp/tree/master/src/core/components <code>src/core/components</code>] and [https://github.com/moodlehq/moodleapp/tree/master/src/core/directives <code>src/core/directives</code>].
====<code>core-format-text</code>====
This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies <code>core-external-content</code> and <code>core-link</code> to all the links and embedded media.

Data that can be passed to the directive:
* <code>text</code> (string) — The text to format.
* <code>siteId</code> (string) — Optional. Site ID to use. If not defined, it will use the id of the current site.
* <code>component</code> (string) — Optional. Component to use when downloading embedded files.
* <code>componentId</code> (string|number) — Optional. ID to use in conjunction with the component.
* <code>adaptImg</code> (boolean) — Optional, defaults to <code>true</code>. Whether to adapt images to screen width.
* <code>clean</code> (boolean) — Optional, defaults to <code>false</code>. Whether all HTML tags should be removed.
* <code>singleLine</code> (boolean) — Optional, defaults to <code>false</code>. Whether new lines should be removed to display all the text in single line. Only if <code>clean</code> is <code>true</code>.
* <code>maxHeight</code> (number) — Optional. Max height in pixels to render the content box. The minimum accepted value is 50. Using this parameter will force <code>display: block</code> to calculate the height better. If you want to avoid this, use <code>class="inline"</code> at the same time to use <code>display: inline-block</code>.
* <code>fullOnClick</code> (boolean) — Optional, defaults to <code>false</code>. Whether it should open a new page with the full contents on click. Only if <code>maxHeight</code> is set and the content has been collapsed.
* <code>fullTitle</code> (string) — Optional, defaults to <code>"Description"</code>. Title to use in full view.

Example usage:
<syntaxhighlight lang="html+ng2">
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</syntaxhighlight>
====<code>core-link</code>====
Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside <code>core-format-text</code>.

Data that can be passed to the directive:
* <code>capture</code> (boolean) — Optional, defaults to <code>false</code>. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* <code>inApp</code> (boolean) — Optional, defaults to <code>false</code>. Whether to open in an embedded browser within the app or in the system browser.
* <code>autoLogin</code> (string) — Optional, defaults to <code>"check"</code>. If the link should be open with auto-login. Accepts the following values:
** <code>"yes"</code> — Always auto-login.
** <code>"no"</code> — Never auto-login.
** <code>"check"</code> — Auto-login only if it points to the current site.

Example usage:
<syntaxhighlight lang="html+ng2">
<a href="<% cm.url %>" core-link>
</syntaxhighlight>
====<code>core-external-content</code>====
Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside <code>core-format-text</code>.

Data that can be passed to the directive:
* <code>siteId</code> (string) — Optional. Site ID to use. If not defined, it will use the id of the current site.
* <code>component</code> (string) — Optional. Component to use when downloading embedded files.
* <code>componentId</code> (string|number) — Optional. ID to use in conjunction with the component.

Example usage:
<syntaxhighlight lang="html+ng2">
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</syntaxhighlight>
====<code>core-user-link</code>====
Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:
* <code>userId</code> (number) — User id to open the profile.
* <code>courseId</code> (number) — Optional. Course id to show the user info related to that course.

Example usage:
<syntaxhighlight lang="html+ng2">
<a ion-item core-user-link userId="<% userid %>">
</syntaxhighlight>
====<code>core-file</code>====
Component to handle a remote file. It shows the file name, icon (depending on mime type) and a button to download or refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:
* <code>file</code> (object) — The file. Must have a <code>filename</code> property and either <code>fileurl</code> or <code>url</code>.
* <code>component</code> (string) — Optional. Component the file belongs to.
* <code>componentId</code> (string|number) — Optional. ID to use in conjunction with the component.
* <code>canDelete</code> (boolean) — Optional. Whether the file can be deleted.
* <code>alwaysDownload</code> (boolean) — Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* <code>canDownload</code> (boolean) — Optional, defaults to <code>true</code>. Whether file can be downloaded.

Example usage:
<syntaxhighlight lang="html+ng2">
<core-file
[file]="{
fileurl: '<% issue.url %>',
filename: '<% issue.name %>',
timemodified: '<% issue.timemodified %>',
filesize: '<% issue.size %>'
}"
component="mod_certificate"
componentId="<% cm.id %>">
</core-file>
</syntaxhighlight>
====<code>core-download-file</code>====
Directive to allow downloading and opening a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the <code>core-file</code> component since it also displays the state of the file.

Data that can be passed to the directive:
* <code>core-download-file</code> (object) — The file to download.
* <code>component</code> (string) — Optional. Component to link the file to.
* <code>componentId</code> (string|number) — Optional. Component ID to use in conjunction with the component.

Example usage (a button to download a file):
<syntaxhighlight lang="html+ng2">
<ion-button
[core-download-file]="{
fileurl: <% issue.url %>,
timemodified: <% issue.timemodified %>,
filesize: <% issue.size %>
}"
component="mod_certificate"
componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</ion-button>
</syntaxhighlight>
====<code>core-course-download-module-main-file</code>====
Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like <code>mod_resource</code>.

This directive must receive either a <code>module</code> or a <code>moduleId</code>. If no files are provided, it will use <code>module.contents</code>.

Data that can be passed to the directive:
* <code>module</code> (object) — Optional, required if module is not supplied. The module object.
* <code>moduleId</code> (number) — Optional, required if module is not supplied. The module ID.
* <code>courseId</code> (number) — The course ID the module belongs to.
* <code>component</code> (string) — Optional. Component to link the file to.
* <code>componentId</code> (string|number) — Optional, defaults to the same value as <code>moduleId</code>. Component ID to use in conjunction with the component.
* <code>files</code> (object[]) — Optional. List of files of the module. If not provided, uses <code>module.contents</code>.

Example usage:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" core-course-download-module-main-file moduleId="<% cmid %>"
courseId="<% certificate.course %>" component="mod_certificate"
[files]="[{
fileurl: '<% issue.fileurl %>',
filename: '<% issue.filename %>',
timemodified: '<% issue.timemodified %>',
mimetype: '<% issue.mimetype %>',
}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</syntaxhighlight>
====<code>core-navbar-buttons</code>====
Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <code><ion-buttons></code> found in the header.

You can use the <code>[hidden]</code> input to hide all the inner buttons if a certain condition is met.

Example usage:
<syntaxhighlight lang="html+ng2">
<core-navbar-buttons end>
<ion-button (click)="action()">
<ion-icon slot="icon-only" name="funnel"></ion-icon>
</ion-button>
</core-navbar-buttons>
</syntaxhighlight>
You can also use this to add options to the context menu, for example:
<syntaxhighlight lang="html+ng2">
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item
[priority]="500" content="Nice boat" (action)="boatFunction()"
iconAction="boat">
</core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</syntaxhighlight>
===Specific component and directives for plugins===
These are component and directives created specifically for supporting Moodle plugins.
====<code>core-site-plugins-new-content</code>====
Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:
* <code>component</code> (string) — The component of the new content.
* <code>method</code> (string) — The method to get the new content.
* <code>args</code> (object) — The params to get the new content.
* <code>preSets</code> (object) — Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* <code>title</code> (string) — The title to display with the new content. Only if <code>samePage</code> is <code>false</code>.
* <code>samePage</code> (boolean) — Optional, defaults to <code>false</code>. Whether to display the content in same page or open a new one.
* <code>useOtherData</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the arguments for the new <code>get_content</code> call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that doing <code>[useOtherData]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].

Let's see some examples.

A button to go to a new content page:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-new-content
title="<% certificate.name %>" component="mod_certificate"
method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</ion-button>
</syntaxhighlight>
A button to load new content in current page using <code>userid</code> from <code>otherdata</code>:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-new-content
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</ion-button>
</syntaxhighlight>
====<code>core-site-plugins-call-ws</code>====
Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see [[#core-site-plugins-call-ws-new-content|<code>core-site-plugins-call-ws-new-content</code>]].

Data that can be passed to the directive:
* <code>name</code> (string) — The name of the WS to call.
* <code>params</code> (object) — The params for the WS call.
* <code>preSets</code> (object) — Extra options for the WS call: whether to use cache or not, etc.
* <code>useOtherDataForWS</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that <code>[useOtherDataForWS]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].
* <code>confirmMessage</code> (string) — Message to confirm the action when theuser clicks the element. If not supplied, no confirmation will be requested. If supplied but empty, "Are you sure?" will be used.
* <code>showError</code> (boolean) — Optional, defaults to <code>true</code>. Whether to show an error message if the WS call fails. This field was added in 3.5.2.
* <code>successMessage</code> (string) — Message to show on success. If not supplied, no message. If supplied but empty, defaults to "Success".
* <code>goBackOnSuccess</code> (boolean) — Whether to go back if the WS call is successful.
* <code>refreshOnSuccess</code> (boolean) — Whether to refresh the current view if the WS call is successful.
* <code>onSuccess</code> (Function) — A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in 3.5.2.
* <code>onError</code> (Function) — A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in 3.5.2.
* <code>onDone</code> (Function) — A function to call when the WS call finishes (either success or fail). This field was added in 3.5.2.

Let's see some examples.

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
[preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage
refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</ion-button>
</syntaxhighlight>
A button to send some data to the server using cache without confirming, going back on success and using <code>userid</code> from <code>otherdata</code>:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</ion-button>
</syntaxhighlight>
Same as the previous example, but implementing custom JS code to run on success:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
[useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</ion-button>
</syntaxhighlight>
In the JavaScript side, you would do:
<syntaxhighlight lang="javascript">
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</syntaxhighlight>
====<code>core-site-plugins-call-ws-new-content</code>====
Directive to call a WS when the element is clicked and load a new content passing the WS result as arguments. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see [[#core-site-plugins-call-ws|<code>core-site-plugins-call-ws</code>]].

Data that can be passed to the directive:
* <code>name</code> (string) — The name of the WS to call.
* <code>params</code> (object) — The parameters for the WS call.
* <code>preSets</code> (object) — Extra options for the WS call: whether to use cache or not, etc.
* <code>useOtherDataForWS</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that <code>[useOtherDataForWS]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].
* <code>confirmMessage</code> (string) — Message to confirm the action when theuser clicks the element. If not supplied, no confirmation will be requested. If supplied but empty, "Are you sure?" will be used.
* <code>showError</code> (boolean) — Optional, defaults to <code>true</code>. Whether to show an error message if the WS call fails. This field was added in 3.5.2.
* <code>component</code> (string) — The component of the new content.
* <code>method</code> (string) — The method to get the new content.
* <code>args</code> (object) — The parameters to get the new content.
* <code>title</code> (string) — The title to display with the new content. Only if <code>samePage</code> is <code>false</code>.
* <code>samePage</code> (boolean) — Optional, defaults to <code>false</code>. Whether to display the content in the same page or open a new one.
* <code>useOtherData</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the arguments for the new <code>get_content</code> call. The format is the same as in <code>useOtherDataForWS</code>.
* <code>jsData</code> (any) — JS variables to pass to the new page so they can be used in the template or JS. If <code>true</code> is supplied instead of an object, all initial variables from current page will be copied. This field was added in 3.5.2.
* <code>newContentPreSets</code> (object) — Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in 3.6.0.
* <code>onSuccess</code> (Function) — A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in 3.5.2.
* <code>onError</code> (Function) — A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in 3.5.2.
* <code>onDone</code> (Function) — A function to call when the WS call finishes (either success or fail). This field was added in 3.5.2.

Let's see some examples.

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws-new-content
name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}"
[preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage
title="<% certificate.name %>" component="mod_certificate"
method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</ion-button>
</syntaxhighlight>
A button to get some data from the server using cache, without confirm, displaying new content in same page and using <code>userid</code> from <code>otherdata</code>:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws-new-content
name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}"
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}"
samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</ion-button>
</syntaxhighlight>

Same as the previous example, but implementing a custom JS code to run on success:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws-new-content
name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}"
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}"
samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</ion-button>
</syntaxhighlight>
In the JavaScript side, you would do:
<syntaxhighlight lang="javascript">
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</syntaxhighlight>
====<code>core-site-plugins-call-ws-on-load</code>====
Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see [[#core-site-plugins-call-ws|<code>core-site-plugins-call-ws</code>]].
* <code>name</code> (string) — The name of the WS to call.
* <code>params</code> (object) — The parameters for the WS call.
* <code>preSets</code> (object) — Extra options for the WS call: whether to use cache or not, etc.
* <code>useOtherDataForWS</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that <code>[useOtherDataForWS]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].
* <code>onSuccess</code> (Function) — A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in 3.5.2.
* <code>onError</code> (Function) — A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in 3.5.2.
* <code>onDone</code> (Function) — A function to call when the WS call finishes (either success or fail). This field was added in 3.5.2.

Example usage:
<syntaxhighlight lang="html+ng2">
<span core-site-plugins-call-ws-on-load
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
[preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)">
</span>
</syntaxhighlight>
In the JavaScript side, you would do:
<syntaxhighlight lang="javascript">
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</syntaxhighlight>
==Advanced features==
===Display the plugin only if certain conditions are met===
You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the initialisation method (for more info, please see the [[#Initialisation|Initialisation]] section ahead).

All initialisation methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return the following in the initialisation method (only for Moodle site 3.8 and onwards):
<syntaxhighlight lang="php">
return ['disabled' => true];
</syntaxhighlight>
If the Moodle site is older than 3.8, then the initialisation method should return this instead:
<syntaxhighlight lang="php">
return ['javascript' => 'this.HANDLER_DISABLED'];
</syntaxhighlight>
On the other hand, you might want to display a plugin only for certain courses (<code>CoreCourseOptionsDelegate</code>) or only if the user is viewing certain users' profiles (<code>CoreUserDelegate</code>). This can be achieved with the initialisation method too.

In the initialisation method you can return a <code>restrict</code> property with two fields in it: <code>courses</code> and <code>users</code>. If you return a list of courses IDs in this property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.
===Using <code>otherdata</code>===
The values returned by the functions in <code>otherdata</code> are added to a variable so they can be used both in JavaScript and in templates. The <code>otherdata</code> returned by an initialisation call is added to a variable named <code>INIT_OTHERDATA</code>, while the <code>otherdata</code> returned by a <code>get_content</code> WS call is added to a variable named <code>CONTENT_OTHERDATA</code>.

The <code>otherdata</code> returned by an initialisation call will be passed to the JS and template of all the <code>get_content</code> calls in that handler. The <code>otherdata</code> returned by a <code>get_content</code> call will only be passed to the JS and template returned by that <code>get_content</code> call.

This means that, in your JavaScript, you can access and use the data like this:
<syntaxhighlight lang="javascript">
this.CONTENT_OTHERDATA.myVar;
</syntaxhighlight>
And in the template you could use it like this:
<syntaxhighlight lang="html+ng2">
{{ CONTENT_OTHERDATA.myVar }}
</syntaxhighlight>
<code>myVar</code> is the name we put to one of our variables, it can be any name that you want. In the example above, this is the <code>otherdata</code> returned by the PHP method:
<syntaxhighlight lang="php">
['myVar' => 'Initial value']
</syntaxhighlight>
====Example====
In our plugin, we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain Web Service. This can be done using <code>otherdata</code>.

We will return the initial value of the input in the <code>otherdata</code> of our PHP method:
<syntaxhighlight lang="php">
'otherdata' => ['myVar' => 'My initial value'],
</syntaxhighlight>
Then in the template we will use it like this:
<syntaxhighlight lang="html+ng2">
<ion-item text-wrap>
<ion-label position="stacked">{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<ion-button expand="block" color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</ion-button>
</ion-item>
</syntaxhighlight>
In the example above, we are creating an input text and we use <code>[(ngModel)]</code> to use the value in <code>myVar</code> as the initial value and to store the changes in the same <code>myVar</code> variable. This means that the initial value of the input will be "My initial value", and if the user changes the value of the input these changes will be applied to the <code>myVar</code> variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the <code>core-site-plugins-call-ws</code> directive. We use the <code>useOtherDataForWS</code> attribute to specify which variable from <code>otherdata</code> we want to send to our WebService. So if the user enters "A new value" in the input and then clicks the button, it will call the WebService <code>mod_certificate_my_webservice</code> and will send as a parameter <code>['myVar' => 'A new value']</code>.

We can also achieve the same result using the <code>params</code> attribute of the <code>core-site-plugins-call-ws</code> directive instead of using <code>useOtherDataForWS</code>:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" color="light" core-site-plugins-call-ws
name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</ion-button>
</syntaxhighlight>
The Web Service call will be exactly the same with both versions.

Notice that this example could be done without using <code>otherdata</code> too, using the <code>form</code> input of the <code>core-site-plugins-call-ws</code> directive.
===Running JS code after a content template has loaded===
When you return JavaScript code from a handler function using the <code>javascript</code> array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use <code>setTimeout</code> to call it. For example:
<syntaxhighlight lang="php">
return [
'template' => [
// ...
],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => [],
];
</syntaxhighlight>
Notice that if you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an initialisation template, so that it does not get loaded again with each page of content.
===JS functions visible in the templates===
The app provides some JavaScript functions that can be used from the templates to update, refresh or view content. These are the functions:
* <code>openContent(title: string, args: any, component?: string, method?: string)</code> — Open a new page to display some new content. You need to specify the <code>title</code> of the new page and the <code>args</code> to send to the method. If <code>component</code> and <code>method</code> aren't provided, it will use the same as in the current page.
* <code>refreshContent(showSpinner = true)</code> — Refresh the current content. By default, it will display a spinner while refreshing. If you don't want it to be displayed, you should pass <code>false</code> as a parameter.
* <code>updateContent(args: any, component?: string, method?: string)</code> — Refresh the current content using different parameters. You need to specify the <code>args</code> to send to the method. If <code>component</code> and <code>method</code> aren't provided, it will use the same as in the current page.
====Examples====
=====Group selector=====
Imagine we have an activity that uses groups and we want to let the user select which group they want to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down, we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's <code>ngModel</code>.
======Using plain HTML======
We need to add a <code>selected</code> attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:
<syntaxhighlight lang="php">
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = [
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups,
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
];
</syntaxhighlight>
In the code above, we're retrieving the groups the user can see and then we're adding a <code>selected</code> boolean to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:
<syntaxhighlight lang="html+handlebars">
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</syntaxhighlight>
The <code>ionChange</code> function will be called every time the user selects a different group with the drop down. We're using the <code>updateContent</code> function to update the current view using the new group. <code>$event</code> is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.
======Using <code>ngModel</code>======
<code>ngModel</code> is an Angular directive that allows storing the value of a certain input or select in a JavaScript variable, and also the opposite way: tell the input or select which value to set. The main problem is that we cannot initialise a JavaScript variable from the template, so we'll use <code>otherdata</code>.

In the PHP function we'll return the group that needs to be selected in the <code>otherdata</code> array:
<syntaxhighlight lang="php">
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

// ...

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'otherdata' => [
'group' => $groupid,
],
];
</syntaxhighlight>
In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the group id in the <code>otherdata</code> array. As it's explained in the [[#Using_otherdata|Using <code>otherdata</code>]] section, this <code>otherdata</code> is visible in the templates inside a variable named <code>CONTENT_OTHERDATA</code>. So in the template we'll use this variable like this:
<syntaxhighlight lang="html+handlebars">
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group"
(ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})"
interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</syntaxhighlight>
===Use the rich text editor===
The rich text editor included in the app requires a <code>FormControl</code> to work. You can use the <code>FormBuilder</code> library to create this control (or to create a whole <cide>FormGroup if you prefer).

With the following JavaScript you'll be able to create a <code>FormControl</code>:
<syntaxhighlight lang="javascript">
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</syntaxhighlight>
In the example above we're using a value returned in <code>OTHERDATA</code> as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:
<syntaxhighlight lang="html+ng2">
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer">
</core-rich-text-editor>
</ion-item>
</syntaxhighlight>
Finally, there are several ways to send the value in the rich text editor to a Web Service to save it. This is one of the simplest options:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ...
</syntaxhighlight>
As you can see, we're passing the value of the rich text editor as a parameter to our Web Service.
===Initialisation===
All handlers can specify an <code>init</code> method in the <code>mobile.php</code> file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the <code>tool_mobile_get_content</code> Web Service with the initialisation method. This WS call will only receive the default arguments.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the <code>mobile.php</code> data.

The templates returned by this method will be added to a <code>INIT_TEMPLATES</code> variable that will be passed to all the JavaScript code of that handler. This means that the JavaScript returned by the initialisation method or the main method can access any of the templates HTML like this:
<syntaxhighlight lang="javascript">
this.INIT_TEMPLATES['main'];
</syntaxhighlight>
In this case, <code>main</code> is the ID of the template we want to use.

The same happens with the <code>otherdata</code> returned by the initialisation method, it is added to an <code>INIT_OTHERDATA</code> variable.

The <code>restrict</code> field returned by this call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate <code>CoreCourseOptionsDelegate</code> and you return a list of course ids in <code>restrict.courses</code>, then your handler will only be enabled in the courses you returned. This only applies to the default handlers, if you register your own handler using the JavaScript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this initialisation JavaScript code, all the properties of that object will be passed to all the JavaScript code of that handler so you can use them when the code is run. For example, if your JavaScript code does something like this:
<syntaxhighlight lang="javascript">
var result = {
MyAddonClass: new MyAddonClass()
};

result;
</syntaxhighlight>
Then, for the rest of JavaScript code of your handler (for example, the main method) you can use this variable like this:
<syntaxhighlight lang="javascript">
this.MyAddonClass
</syntaxhighlight>
====Examples====
=====Link handlers=====
A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your plugin page when a link to your plugin is clicked.

After the 4.0 version, the Moodle app automatically creates two link handlers for module plugins, you don't need to create them in your plugin's Javascript code anymore:

* A handler to treat links to ''mod/pluginanme/view.php?id=X''. When this link is clicked, it will open your module in the app.
* A handler to treat links to ''mod/pluginname/index.php?id=X''. When this link is clicked, it will open a page in the app listing all the modules of your type inside a certain course.

Link handlers have some advanced features that allow you to change how links behave under different conditions.

======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<syntaxhighlight lang="javascript">
class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

constructor() {
super();

this.pattern = RegExp('\/mod\/foo\/specialpage.php');
}

}
</syntaxhighlight>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority; the handler with the highest priority will be used.

All default handlers have a priority of 0, so 1 or higher will override the default.
<syntaxhighlight lang="javascript">
class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

constructor() {
super();

this.priority = 1;
}

}
</syntaxhighlight>
======Multiple actions======
Once a link has been matched, the handler's <code>getActions()</code> method determines what the link should do. This method has access to the URL and its parameters.

Different actions can be returned depending on different conditions.
<syntaxhighlight lang="javascript">
class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

getActions(siteIds, url, params) {
return [
{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [
// ...
],
},
{
// ...
},
];
}

}
</syntaxhighlight>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first valid action will be used to open the link.

If your handler is matched with a link, but a condition assessed in the <code>getActions()</code> method means you want to revert to the next highest priorty handler, you can invalidate your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing <code>/mod/foo/</code>, and force those with an id parameter that's not in the <code>supportedModFoos</code> array to open in the user's browser, rather than the app.
<syntaxhighlight lang="javascript">
const that = this;
const supportedModFoos = [...];

class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

constructor() {
super();

this.pattern = new RegExp('\/mod\/foo\/');
this.name = 'AddonModFooLinkHandler';
this.priority = 1;
}

getActions(siteIds, url, params) {
const action = {
action() {
that.CoreUtilsProvider.openInBrowser(url);
},
};

if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}

return [action];
}

}

this.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</syntaxhighlight>
=====Module prefetch handler=====
The <code>CoreCourseModuleDelegate</code> handler allows you to define a list of offline functions to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using offline functions.

Here’s an example on how to create a prefetch handler using the initialisation JS:
<syntaxhighlight lang="javascript">
// Create a class that extends from CoreCourseActivityPrefetchHandlerBase.
class AddonModCertificateModulePrefetchHandler extends CoreCourseActivityPrefetchHandlerBase {

constructor() {
super();

this.name = 'AddonModCertificateModulePrefetchHandler';
this.modName = 'certificate';

// This must match the plugin identifier from db/mobile.php,
// otherwise the download link in the context menu will not update correctly.
this.component = 'mod_certificate';
this.updatesNames = /^configuration$|^.*files$/;
}

// Override the prefetch call.
prefetch(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
}

}

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</syntaxhighlight>
One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same <code>cmid</code>. The app will not automatically work with this situation — it will call the offline function with the standard arguments only — so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function, the rest of the code is as above) where there are multiple values of a custom <code>section</code> parameter for the mobile function <code>mobile_document_view</code>:
<syntaxhighlight lang="javascript">
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</syntaxhighlight>
=====Single activity course format=====
In the following example, the value of <code>INIT_TEMPLATES['main']</code> is:
<syntaxhighlight lang="html+ng2">
<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>
</syntaxhighlight>
This template is returned by the initialisation method. And this is the JavaScript code returned:
<syntaxhighlight lang="javascript">
var that = this;

class AddonSingleActivityFormatComponent {

constructor() {
this.data = {};
}

ngOnChanges(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
}

doRefresh(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
}

}

class AddonSingleActivityFormatHandler {

constructor() {
this.name = 'singleactivity';
}

isEnabled() {
return true;
}

canViewAllSections() {
return false;
}

getCourseTitle(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || '';
}

displayEnableDownload() {
return false;
}

displaySectionSelector() {
return false;
}

getCourseFormatComponent() {
return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES['main'], AddonSingleActivityFormatComponent);
}

}

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</syntaxhighlight>
===Using the JavaScript API===
The JavaScript API is only supported by the delegates specified in the [[#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] section. This API allows you to override any of the functions of the default handler.

The <code>method</code> specified in a handler registered in the <code>CoreUserProfileFieldDelegate</code> will be called immediately after the initialisation method, and the JavaScript returned by this method will be run. If this JavaScript code returns an object with certain functions, these functions will override the ones in the default handler.

For example, if the JavaScript returned by the method returns something like this:
<syntaxhighlight lang="javascript">
var result = {
getData: function(field, signup, registerAuth, formValues) {
// ...
}
};
result;
</syntaxhighlight>
The the <code>getData</code> function of the default handler will be overridden by the returned <code>getData</code> function.

The default handler for <code>CoreUserProfileFieldDelegate</code> only has 2 functions: <code>getComponent</code> and <code>getData</code>. In addition, the JavaScript code can return an extra function named <code>componentInit</code> that will be executed when the component returned by <code>getComponent</code> is initialised.

Here’s an example on how to support the text user profile field using this API:
<syntaxhighlight lang="javascript">
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = 'profile_field_' + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || '';
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? 'password' : 'text';

var formData = {
value: this.field.defaultdata,
disabled: this.disabled,
};

this.form.addControl(this.field.modelName,
that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = 'profile_field_' + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name]),
};
}
};

result;
</syntaxhighlight>
===Translate dynamic strings===
If you wish to have an element that displays a localised string based on value from your template you can doing something like:
<syntaxhighlight lang="html+handlebars">
<ion-card>
<ion-card-content>
{{ 'plugin.mod_myactivity.<% status %>' | translate }}
</ion-card-content>
</ion-card>
</syntaxhighlight>
This could save you from having to write something like when only one value should be displayed:
<syntaxhighlight lang="html+handlebars">
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</syntaxhighlight>
===Using strings with dates===
If you have a string that you wish to pass a formatted date, for example in the Moodle language file you have:
<syntaxhighlight lang="php">
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</syntaxhighlight>
You can localise the string correctly in your template using something like the following:
<syntaxhighlight lang="html+handlebars">
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</syntaxhighlight>
A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, whereas Unix timestamps are in seconds.
===Support push notification clicks===
If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a <code>contexturl</code> in your notification. When the notification is clicked, the app will try to open the <code>contexturl</code>.

Please notice that the <code>contexturl</code> will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a <code>customdata</code> array that contains an <code>appurl</code> property:
<syntaxhighlight lang="php">
$notification->customdata = [
'appurl' => $myurl->out(),
];
</syntaxhighlight>
In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[#Advanced_link_handler|creating an advanced link handler]], but you'll have to use <code>CorePushNotificationsDelegate</code> and your handler will have to implement the properties and functions defined in the [https://github.com/moodlehq/moodleapp/blob/master/src/core/features/pushnotifications/services/push-delegate.ts#L27 CorePushNotificationsClickHandler] interface.
===Implement a module similar to mod_label===
In Moodle 3.8 or higher, if your plugin doesn't support <code>FEATURE_NO_VIEW_LINK</code> and you don't specify a <code>coursepagemethod</code> then the module will only display the module description in the course page and it won't be clickable in the app, just like <code>mod_label</code>. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in <code>displaydata</code>).

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the <code>coursepagemethod</code> property in <code>mobile.php</code>. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only plain HTML.

If you don't want your module to be clickable then you just need to remove <code>method</code> from <code>mobile.php</code>. With these 2 changes you can have a module that behaves like <code>mod_label</code> in the app.
===Use Ionic navigation lifecycle functions===
Ionic let pages define some functions that will be called when certain navigation lifecycle events happen. For more info about these functions, see [https://ionicframework.com/docs/api/router-outlet Ionic's documentation].

You can define these functions in your plugin javascript:
<syntaxhighlight lang="javascript">
this.ionViewWillLeave = function() {
// ...
};</syntaxhighlight>
In addition to that, you can also implement <code>canLeave</code> to use Angular route guards:
<syntaxhighlight lang="javascript">
this.canLeave = function() {
// ...
};</syntaxhighlight>
So for example you can make your plugin ask for confirmation if the user tries to leave the page when he has some unsaved data.
===Module plugins: dynamically determine if a feature is supported===
In Moodle you can specify if your plugin supports a certain feature, like <code>FEATURE_NO_VIEW_LINK</code>. If your plugin will always support or not a certain feature, then you can use the <code>supportedfeatures</code> property in <code>mobile.php</code> to specify it ([[#Options_only_for_CoreCourseModuleDelegate|see more documentation about this]]). But if you need to calculate it dynamically then you will have to create a function to calculate it.

This can be achieved using the initialisation method (for more info, please see the [[#Initialisation|Initialisation]] section above). The JavaScript returned by your initialisation method will need to define a function named <code>supportsFeature</code> that will receive the name of the feature:
<syntaxhighlight lang="javascript">
var result = {
supportsFeature: function(featureName) {
// ...
}
};
result;
</syntaxhighlight>
Currently the app only uses <code>FEATURE_MOD_ARCHETYPE</code> and <code>FEATURE_NO_VIEW_LINK</code>.
== Testing ==
You can also write automated tests for your plugin using Behat, you can read more about it on the [[Acceptance testing for the Moodle App]] page.
== Upgrading plugins from an older version ==
If you added mobile support to your plugin for the Ionic 3 version of the app (previous to the 3.9.5 release), you will probably need to make some changes to make it compatible with Ionic 5.

Learn more at the [[Moodle App Plugins Upgrade Guide]].
==Troubleshooting==
=== Invalid response received ===
You might receive this error when using the <code>core-site-plugins-call-ws</code> directive or similar. By default, the app expects all Web Service calls to return an object, if your Web Service returns another type (string, boolean, etc.) then you need to specify it using the <code>preSets</code> attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:
<syntaxhighlight lang="html+ng2">
[preSets]="{typeExpected: 'boolean'}"
</syntaxhighlight>
In a similar way, if your Web Service returns <code>null</code> you need to tell the app not to expect any result using <code>preSets</code>:
<syntaxhighlight lang="html+ng2">
[preSets]="{responseExpected: false}"
</syntaxhighlight>
=== Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS ===
Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, <code>ion-radio</code>, <code>ion-checkbox</code> and <code>ion-select</code> don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the Web Service.

There are 2 workarounds to fix this problem.
==== Sending the data manually ====
The first solution is to send the missing params manually using the <code>params</code> property. We will use <code>ngModel</code> to store the input value in a variable, and this variable will be passed to the parameters. Please notice that <code>ngModel</code> requires the element to have a name, so if you add <code>ngModel</code> to a certain element you need to add a name too.

For example, if you have a template like this:
<syntaxhighlight lang="html+ng2">
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<ion-button expand="block" type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</ion-button>
</syntaxhighlight>
Then you should modify it like this:
<syntaxhighlight lang="html+ng2">
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<ion-button expand="block" type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</ion-button>
</syntaxhighlight>
Basically, you need to add <code>ngModel</code> to the affected element (in this case, the <code>radio-group</code>). You can put whatever name you want as the value, we used "responses". With this, every time the user selects a radio button the value will be stored in a variable called "responses". Then, in the button we are passing this variable to the parameters of the Web Service.

Please notice that the <code>form</code> attribute has priority over <code>params</code>, so if you have an input with <code>name="responses"</code> it will override what you're manually passing to <code>params</code>.
==== Using a hidden input ====
Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use <code>ngModel</code> to synchronise your radio/checkbox/select with the new hidden input. Please notice that <code>ngModel</code> requires the element to have a name, so if you add <code>ngModel</code> to a certain element you need to add a name too.

For example, if you have a radio button like this:
<syntaxhighlight lang="html+ng2">
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</syntaxhighlight>
Then you should modify it like this:
<syntaxhighlight lang="html+ng2">
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</syntaxhighlight>
In the example above, we're using a variable called "responses" to synchronise the data between the <code>radio-group</code> and the hidden input. You can use whatever name you want.
=== I can't return an object or array in <code>otherdata</code> ===
If you try to return an object or an array in any field inside <code>otherdata</code>, the Web Service call will fail with the following error:
<syntaxhighlight lang="text">
Scalar type expected, array or object received
</syntaxhighlight>
Each field in <code>otherdata</code> must be a string, number or boolean; it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:
<syntaxhighlight lang="php">
'otherdata' => ['data' => json_encode($data)],
</syntaxhighlight>
The app will automatically parse this JSON and convert it back into an array or object.
==Examples==
===Accepting dynamic names in a Web Service===
We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new Web Service that we have created.

The first issue we find is that the Web Service needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the <code>_parameters()</code> function of our new Web Service, we will add this parameter:
<syntaxhighlight lang="php">
'data' => new external_multiple_structure(
new external_single_structure(
[
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
]
),
'The data to be saved', VALUE_DEFAULT, []
)
</syntaxhighlight>
Now we need to adapt our form to send the data as the Web Service requires it. In our template, we have a button with the <code>core-site-plugins-call-ws</code> directive that will send the form data to our Web Service. To make this work we will have to pass the parameters manually, without using the <code>form</code> attribute, because we need to format the data before it is sent.

Since we will send the parameters manually and we want it all to be sent in the same array, we will use <code>ngModel</code> to store the input data into a variable that we'll call <code>data</code>, but you can use the name you want. This variable will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:
<syntaxhighlight lang="javascript">
{a1: 'My answer'}
</syntaxhighlight>
So we need to add <code>ngModel</code> to all the inputs whose values need to be sent to the <code>data</code> WS param. Please notice that <code>ngModel</code> requires the element to have a name, so if you add <code>ngModel</code> to a certain element you need to add a name too. For example:
<syntaxhighlight lang="html+ng2">
<ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']">
</syntaxhighlight>
As you can see, we're using <code>CONTENT_OTHERDATA</code> to store the data. We do it like this because we'll use <code>otherdata</code> to initialise the form, setting the values the user has already stored. If you don't need to initialise the form, then you can use the <code>dataObject</code> variable, an empty object that the mobile app creates for you:
<syntaxhighlight lang="html+ng2">
[(ngModel)]="dataObject['<% name %>']"
</syntaxhighlight>
The app has a function that allows you to convert this data object into an array like the one the WS expects: <code>objectToArrayOfObjects</code>. So in our button we'll use this function to format the data before it's sent:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</syntaxhighlight>
As you can see in the example above, we're specifying that the keys of the <code>data</code> object need to be stored in a property called "name", and the values need to be stored in a property called "value". If your Web Service expects different names you need to change the parameters of the <code>objectToArrayOfObjects</code> function.

If you open your plugin now in the app it will display an error in the JavaScript console. The reason is that the <code>data</code> variable doesn't exist inside <code>CONTENT_OTHERDATA</code>. As it is explained in previous sections, <code>CONTENT_OTHERDATA</code> holds the data that you return in <code>otherdata</code> for your method. We'll use <code>otherdata</code> to initialise the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialise the <code>data</code> object as an empty object. Please remember that we cannot return arrays or objects in <code>otherdata</code>, so we'll return a JSON string.
<syntaxhighlight lang="php">
'otherdata' => ['data' => '{}'],
</syntaxhighlight>
With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:
<syntaxhighlight lang="php">
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: ['a1' => 'My value'].

// ...

'otherdata' => ['data' => json_encode($userdata)],
</syntaxhighlight>
Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our Web Service in array format.
==Moodle plugins with mobile support==
* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].
See the complete list in [https://moodle.org/plugins/browse.php?list=award&id=6 the plugins database] (it may contain some outdated plugins).
=== Mobile app support award ===
If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email at [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory.
[[Category:Mobile]]
[[Category:Moodle App Ionic 5]]

Moodle App Plugins Development Guide

2022-04-25T06:43:36Z

Dpalou: Document 4.0 changes in CoreCourseFormatDelegate options.

{{Moodle App (Ionic 5)}}
If you want to add mobile support to your Moodle plugin, you can achieve it by extending different areas of the app using ''just PHP server side code'' and providing templates written with [https://ionicframework.com/docs/components Ionic] and custom components.

You will have to:
# Create a <code>db/mobile.php</code> file in your plugin. In this file, you will be able to indicate which areas of the app you want to extend. For example, adding a new option in the main menu, implementing support for a new activity module, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered as html. This html should use Ionic components so that it looks native, but it can be generated using mustache templates.

Let’s clarify some points:
* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function <code>tool_mobile_get_content</code>.
* As arguments of your functions you will always receive the <code>userid</code>, some relevant details of the app (like the app version or the current language in the app), and some specific data depending on the type of plugin (<code>courseid</code>, <code>cmid</code>, ...).
* The mobile app also implements a list of custom Ionic components and directives that provide dynamic behaviour; like indicating that you are linking a file that can be downloaded, allowing a transition to new pages into the app calling a specific function in the server, submitting form data to the server, etc.

==Getting started==
If you only want to write a plugin, it is not necessary that you set up your environment to work with the Moodle App. In fact, you don't even need to compile it. You can just [[Using the Moodle App in a browser|use a Chromium-based browser]] to add mobile support to your plugins!

You can use the app from one of the hosted versions on [https://master.apps.moodledemo.net master.apps.moodledemo.net] (the latest stable version) and [https://integration.apps.moodledemo.net integration.apps.moodledemo.net] (the latest development version). If you need any specific environment (hosted versions are deployed with a ''production'' environment), you can also use [[Moodle App Docker Images|Docker images]]. And if you need to test your plugin in a native device, you can always use [https://download.moodle.org/mobile Moodle HQ's application].

This should suffice for developing plugins. However, if you are working on advanced functionality and you need to run the application from the source code, you can find more information in the [[Moodle App Development Guide]].
===Development workflow===
Before getting into the specifics of your plugin, we recommend that you start adding a simple "Hello World" button in the app to see that everything works properly.

Let's say your plugin is called <code>local_hello</code>, you can start by adding the following files:

<code>db/mobile.php</code>
<syntaxhighlight lang="php">
<?php

$addons = [
'local_hello' => [
'handlers' => [
'hello' => [
'delegate' => 'CoreMainMenuDelegate',
'method' => 'view_hello',
'displaydata' => [
'title' => 'hello',
'icon' => 'earth',
],
],
],
'lang' => [
['hello', 'local_hello'],
],
],
];
</syntaxhighlight>
<code>classes/output/mobile.php</code>
<syntaxhighlight lang="php">
<?php

namespace local_hello\output;

defined('MOODLE_INTERNAL') || die();

class mobile {

public static function view_hello() {
return [
'templates' => [
[
'id' => 'main',
'html' => '<h1 class="text-center">{{ "plugin.local_hello.hello" | translate }}</h1>',
],
],
];
}

}
</syntaxhighlight>
<code>lang/en/local_hello.php</code>
<syntaxhighlight lang="php">
<?php

$string['hello'] = 'Hello World';
</syntaxhighlight>
Once you've done that, try logging into your site in the app and you should see a new button in the main menu or more menu (depending on the device) saying "Hello World". If you press this button, you should see a page saying "Hello World!".

Congratualtions, you have written your first Moodle plugin with moodle support!

You can read the rest of this page to learn more about mobile plugins and start working on your plugin. Here's some things to keep in mind:
* If you change the <code>mobile.php</code> file, you will have to refresh the browser. And remember to [https://developer.chrome.com/docs/devtools/network/reference/#disable-cache disable the network cache].
* If you change an existing template or function, you won’t have to refresh the browser. In most cases, doing a PTR (Pull To Refresh) in the page that displays the template will suffice.
* If any of these doesn't show your changes, you may need to [https://docs.moodle.org/311/en/Developer_tools#Purge_all_caches purge all caches] to avoid problems with the auto-loading cache.
* Ultimately, if that doesn't work either, you may have to log out from the site and log in again. If any changes affect plugin installation, you may also need to increase the version in your plugin's <code>version.php</code> file and upgrade it in the site.
==Types of plugins==
There are 3 types of plugins:
===Templates generated and downloaded when the user opens the plugins===
[[File:Templates_downloaded_when_requested.png|thumb]]
With this type of plugin, the template of your plugin will be generated and downloaded when the user opens the plugin in the app. This means that your function will receive some context parameters. For example, if you're developing a course module plugin you will receive the <code>courseid</code> and the <code>cmid</code> (course module ID). You can see the list of delegates that support this type of plugin in the [[#Delegates|Delegates]] section.
===Templates downloaded on login and rendered using JS data===
[[File:Templates_downloaded_on_login.png|thumb]]
With this type of plugin, the template for your plugin will be downloaded when the user logs in into the app and will be stored in the device. This means that your function will not receive any context parameters, and you need to return a generic template that will be built with JS data like the ones in the Moodle App. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[#Delegates|Delegates]] section.
===Pure JavaScript plugins===
You can always implement the whole plugin yourself using JavaScript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[#Delegates|Delegates]] section.
==Step by step example==
In this example, we are going to update an existing plugin, the [https://github.com/mdjnelson/moodle-mod_certificate Certificate activity module], that previously used a [[Moodle Mobile 2 (Ionic 1) Remote add-ons|Remote add-on]] (a legacy approach to implement mobile plugins).

This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.
===Step 1. Update the <code>db/mobile.php</code> file===
In this case, we are updating an existing file. For new plugins, you should create this new file.
<syntaxhighlight lang="php">
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</syntaxhighlight>
;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields). In this case, we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the [[#Delegates|Delegates]] section for all the possible options.

; Method:
: This is the method in the Moodle <code>\{component-name}\output\mobile</code> class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the <code>mobile.php</code> file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current <code>userid</code> (and <code>courseid</code> when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently <code>userid</code> and <code>courseid</code>).
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the <code>files</code> array).
: Note that if your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a <code>page</code> parameter in addition to the usual <code>cmid</code>, <code>courseid</code>, and <code>userid</code>) then the app will not know which additional parameters to supply. In this case, do not list the function in <code>offlinefunctions</code>; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here, like <code>['cancel', 'moodle']</code>. If you do this, be warned that in the app you will then need to refer to that string as <code><nowiki>{{ 'plugin.myplugin.cancel' | translate }}</nowiki></code> (not <code><nowiki>{{ 'plugin.moodle.cancel' | translate }}</nowiki></code>).
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.
There are additional attributes supported by the <code>mobile.php</code> list, you can find about them in the [[#Mobile.php_supported_options|Mobile.php supported options]] section.
===Step 2. Creating the main function===
The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem <code>classes/output</code> directory, the name of the class must be <code>mobile</code>.

For this example, the namespace name will be <code>mod_certificate\output</code>.

<code>mod/certificate/classes/output/mobile.php</code>
<syntaxhighlight lang="php">
<?php

namespace mod_certificate\output;

use context_module;
use mod_certificate_external;

class mobile {

/**
* Returns the certificate course view for the mobile app.
*
* @param array $args Arguments from tool_mobile_get_content WS.
*
* @return array HTML, JS and other data.
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid, false, $cm, true, true);

$context = \context_module::instance($cm->id);

require_capability('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', ['id' => $cm->instance]);

// Get certificates from external (taking care of exceptions).
try {
$issued = \mod_certificate_external::issue_certificate($cm->instance);
$certificates = \mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = [];
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
[$certificate->intro, $certificate->introformat] =
external_format_text($certificate->intro, $certificate->introformat, $context->id, 'mod_certificate', 'intro');
$data = [
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid,
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</syntaxhighlight>
;Function declaration:
: The function name is the same as the one used in the <code>mobile.php</code> file (<code>method</code> field). There is only one argument, <code>$args</code>, which is an array containing all the information sent by the mobile app (the <code>courseid</code>, <code>userid</code>, <code>appid</code>, <code>appversionname</code>, <code>appversioncode</code>, <code>applang</code>, <code>appcustomurlscheme</code>, ...).

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a <code>view.php</code> script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

; Function return:
* <code>templates</code> — The rendered template (notice that we could return more than one template, but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some JavaScript code.
* <code>javascript</code> — Empty, because we don’t need any in this case.
* <code>otherdata</code> — Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way data-binding in the template.
* <code>files</code> — A list of files that the app should be able to download (for offline usage mostly).
===Step 3. Creating the template for the main function===
This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic, together with directives and components specific to the Moodle App.

All the HTML elements starting with <code>ion-</code> are ionic components. Most of the time, the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML elements starting with <code>core-</code> are custom components of the Moodle App.

<code>mod/certificate/templates/mobile_view_page.mustache</code>
<syntaxhighlight lang="html+handlebars">
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>">
</core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<ion-button expand="block" color="light" core-site-plugins-new-content title="<% certificate.name %>"
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</ion-button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<ion-button expand="block" core-course-download-module-main-file moduleId="<% cmid %>"
courseId="<% certificate.course %>" component="mod_certificate"
[files]="[{
fileurl: '<% issue.fileurl %>',
filename: '<% issue.filename %>',
timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>',
}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate"
[params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}">
</span>
</ion-list>
</div>
</syntaxhighlight>
In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code>core-course-module-description</code>, which is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.

The following line using the <code>translate</code> filter indicates that the app will translate the <code>summaryofattempts</code> string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has the following format:
<syntaxhighlight lang="text">
plugin.{plugin-identifier}.{string-id}
</syntaxhighlight>
Where <code>{plugin-identifier}</code> is taken from <code>mobile.php</code> and <code>{string-id}</code> must be indicated in the <code>lang</code> field in <code>mobile.php</code>.

Then, we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the <code>mobile_issues_view</code> function in the <code>mod_certificate</code> component; passing as arguments the <code>cmid</code> and <code>courseid</code>. The content returned by this function will be displayed in a new page (read the following section to see the code of this new page).

Just after this button, we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available offline.

Finally, just before the <code>ion-list</code> is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call a Web Service function in the server, in this case we are calling the <code>mod_certificate_view_certificate</code> that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.
===Step 4. Adding an additional page===
Add the following method to <code>mod/certificate/classes/output/mobile.php</code>:
<syntaxhighlight lang="php">
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS.
*
* @return array HTML, JS and other data.
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid, false, $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', ['id' => $cm->instance]);

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = [];
}

$data = ['issues' => $issues];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</syntaxhighlight>
This method for the new page was added just after <code>mobile_course_view</code>, the code is quite similar: checks the capabilities, retrieves the information required for the template, and returns the template rendered.

The code of the mustache template is also very simple.

<code>mod/certificate/templates/mobile_view_issues.mustache</code>
<syntaxhighlight lang="html+handlebars">
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</syntaxhighlight>
As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an Ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter <code>coreToLocaleString</code>). We are also displaying the grade displayed in the certificate (if any).
===Step 5. Plugin webservices, if included===
If your plugin uses its own web services, they will also need to be enabled for mobile access in your <code>db/services.php</code> file.

The following line should be included in each webservice definition:
<syntaxhighlight lang="php">
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
</syntaxhighlight>
<code>mod/certificate/db/services.php</code>
<syntaxhighlight lang="php">
<?php

$functions = [
'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</syntaxhighlight>
==Mobile.php supported options==
In the previous section, we learned about some of the existing options for handlers configuration. This is the full list of supported options.
===Common options===
* <code>delegate</code> (mandatory) — Name of the delegate to register the handler in.
* <code>method</code> (mandatory) — The method to call to retrieve the main page content.
* <code>init</code> (optional) — A method to call to retrieve the initialisation JS and the restrictions to apply to the whole handler. It can also return templates that can be used from JavaScript. You can learn more about this in the [[#Initialisation|Initialisation]] section.
* <code>restricttocurrentuser</code> (optional) — Only used if the delegate has a <code>isEnabledForUser</code> function. If true, the handler will only be shown for the current user. For more info about displaying the plugin only for certain users, please see [[#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* <code>restricttoenrolledcourses</code> (optional) — Only used if the delegate has a <code>isEnabledForCourse</code> function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* <code>styles</code> (optional) — An array with two properties: <code>url</code> and <code>version</code>. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* <code>moodlecomponent</code> (optional) — If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be <code>local_whatever</code>, but in <code>moodlecomponent</code> you can specify that this handler will implement <code>format_whatever</code> or <code>mod_whatever</code>. This property was introduced in the version 3.6.1 of the app.
===Options only for CoreMainMenuDelegate ===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the More tab, they cannot be displayed as tabs in the bottom bar.
* <code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreMainMenuHomeDelegate ===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
* <code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreCourseOptionsDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
* <code>ismenuhandler</code> (optional) — Supported from the 3.7.1 version of the app. Set it to <code>true</code> if you want your plugin to be displayed in the contextual menu of the course instead of in the top tabs. The contextual menu is displayed when you click in the 3-dots button at the top right of the course.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreCourseModuleDelegate===
* <code>displaydata</code> (mandatory):
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>method</code> (optional) — The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* <code>offlinefunctions</code> (optional) — List of functions to call when prefetching the module. It can be a <code>get_content</code> method or a WS. You can filter the params received by the WS. By default, WS will receive these params: <code>courseid</code>, <code>cmid</code>, <code>userid</code>. Other valid values that will be added if they are present in the list of params: <code>courseids</code> (it will receive a list with the courses the user is enrolled in), <code>{component}id</code> (For example, <code>certificateid</code>).
* <code>downloadbutton</code> (optional) — Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* <code>isresource</code> (optional) — Whether the module is a resource or an activity. Only used if there is any offline function. If your module relies on the <code>contents</code> field, then it should be <code>true</code>.
* <code>updatesnames</code> (optional) — Only used if there is any offline function. A regular expression to check if there's any update in the module. It will be compared to the result of <code>core_course_check_updates</code>.
* <code>displayopeninbrowser</code> (optional) — Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: <code>this.displayOpenInBrowser = false;</code>. Supported from the 3.6 version of the app.
* <code>displaydescription</code> (optional) — Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: <code>this.displayDescription = false;</code>. Supported from the 3.6 version of the app.
* <code>displayrefresh</code> (optional) — Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: <code>this.displayRefresh = false;</code>. Supported from the 3.6 version of the app.
* <code>displayprefetch</code> (optional) — Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: <code>this.displayPrefetch = false;</code>. Supported from the 3.6 version of the app.
* <code>displaysize</code> (optional) — Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: <code>this.displaySize = false;</code>. Supported from the 3.6 version of the app.
* <code>supportedfeatures</code> (optional) — It can be used to specify the supported features of the plugin. Currently the app only uses <code>FEATURE_MOD_ARCHETYPE</code> and <code>FEATURE_NO_VIEW_LINK</code>. It should be an array with features as keys (For example, <code>[FEATURE_NO_VIEW_LINK => true</code>). If you need to calculate this dynamically please see [[#Module_plugins:_dynamically_determine_if_a_feature_is_supported|Module plugins: dynamically determine if a feature is supported]]. Supported from the 3.6 version of the app.
* <code>coursepagemethod</code> (optional) — If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML. Supported from the 3.8 version of the app.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreCourseFormatDelegate===
* <code>canviewallsections</code> (optional) — Whether the course format allows seeing all sections in a single page. Defaults to <code>true</code>.
* <code>displayenabledownload</code> (optional) — Deprecated in the 4.0 app, it's no longer used.
* <code>displaysectionselector</code> (optional) — Deprecated in the 4.0 app, use ''displaycourseindex'' instead.
*<code>displaycourseindex</code> (optional) — Whether the default course index should be displayed. Defaults to <code>true</code>.
===Options only for CoreUserDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>type</code> — The type of the addon. The values accepted are <code>'newpage'</code> (default) and <code>'communication'</code>.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreSettingsDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for AddonMessageOutputDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreBlockDelegate===
* <code>displaydata</code> (optional):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section. If this is not supplied, it will default to <code>'plugins.block_{block-name}.pluginname'</code>, where <code>{block-name}</code> is the name of the block.
** <code>class</code> — A CSS class. If this is not supplied, it will default to <code>block_{block-name}</code>, where <code>{block-name}</code> is the name of the block.
** <code>type</code> — Possible values are:
*** <code>"title"</code> — Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
*** <code>"prerendered"</code> — Your block will display the content and footer returned by the WebService to get the blocks (for example, <code>core_block_get_course_blocks</code>), so your block's method will never be called.
*** Any other value — Your block will immediately call the method specified in <code>mobile.php</code> and it will use the template to render the block.
* <code>fallback</code> (optional) — This option allows you to specify a block to use in the app instead of your block. For example, you can make the app display the "My overview" block instead of your block in the app by setting <code>'fallback' => 'myoverview'</code>. The fallback will only be used if you don't specify a <code>method</code> and the <code>type</code> is different to <code>'title'</code> or <code>'prerendered'</code>. Supported from the 3.9.0 version of the app.
==Delegates==
Delegates can be classified by type of plugin. For more info about type of plugins, please see the [[#Types_of_plugins|Types of plugins]] section.
===Templates generated and downloaded when the user opens the plugins===
====<code>CoreMainMenuDelegate</code>====
You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).
====<code>CoreMainMenuHomeDelegate</code>====
You must use this delegate when you want to add new tabs in the home page (by default the app is displaying the "Dashboard" and "Site home" tabs).
====<code>CoreCourseOptionsDelegate</code>====
You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).
====<code>CoreCourseModuleDelegate</code>====
You must use this delegate for supporting activity modules or resources.
====<code>CoreUserDelegate</code>====
You must use this delegate when you want to add additional options in the user profile page in the app.
====<code>CoreCourseFormatDelegate</code>====
You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a <code>CoreCourseFormatDelegate</code> handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format.

You can learn more about this at the [[Creating mobile course formats]] page.
====<code>CoreSettingsDelegate</code>====
You must use this delegate to add a new option in the settings page.
====<code>AddonMessageOutputDelegate</code>====
You must use this delegate to support a message output plugin.
====<code>CoreBlockDelegate</code>====
You must use this delegate to support a block. For example, blocks can be displayed in Site Home, Dashboard and the Course page.
===Templates downloaded on login and rendered using JS data===
====<code>CoreQuestionDelegate</code>====
You must use this delegate for supporting question types.

You can learn more about this at the [[Creating mobile question types]] page.
====<code>CoreQuestionBehaviourDelegate</code>====
You must use this delegate for supporting question behaviours.
====<code>CoreUserProfileFieldDelegate</code>====
You must use this delegate for supporting user profile fields.
====<code>AddonModQuizAccessRuleDelegate</code>====
You must use this delegate to support a quiz access rule.
====<code>AddonModAssignSubmissionDelegate</code> and <code>AddonModAssignFeedbackDelegate</code>====
You must use these delegates to support assign submission or feedback plugins.
====<code>AddonWorkshopAssessmentStrategyDelegate</code>====
You must use this delegate to support a workshop assessment strategy plugin.
===Pure JavaScript plugins===
These delegates require JavaScript to be supported. See [[#Initialisation|Initialisation]] for more information.
* <code>CoreContentLinksDelegate</code>
* <code>CoreCourseModulePrefetchDelegate</code>
* <code>CoreFileUploaderDelegate</code>
* <code>CorePluginFileDelegate</code>
* <code>CoreFilterDelegate</code>
==Available components and directives==
===Difference between components and directives===
A directive is usually represented as an HTML attribute, allows you to extend a piece of HTML with additional information or functionality. Example of directives are: <code>core-auto-focus</code>, <code>*ngIf</code>, and <code>ng-repeat</code>.

Components are also directives, but they are usually represented as an HTML tag and they are used to add custom elements to the app. Example of components are <code>ion-list</code>, <code>ion-item</code>, and <code>core-search-box</code>.

Components and directives are Angular concepts; you can learn more about them and the components come out of the box with Ionic in the following links:
* [https://angular.io/guide/built-in-directives Angular directives documentation]
* [https://ionicframework.com/docs/components Ionic components]
===Custom core components and directives===
These are some useful custom components and directives that are only available in the Moodle App. Please note that this isn’t the full list of custom components and directives, it’s just an extract of the most common ones.

You can find a full list of components and directives in the source code of the app, within [https://github.com/moodlehq/moodleapp/tree/master/src/core/components <code>src/core/components</code>] and [https://github.com/moodlehq/moodleapp/tree/master/src/core/directives <code>src/core/directives</code>].
====<code>core-format-text</code>====
This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies <code>core-external-content</code> and <code>core-link</code> to all the links and embedded media.

Data that can be passed to the directive:
* <code>text</code> (string) — The text to format.
* <code>siteId</code> (string) — Optional. Site ID to use. If not defined, it will use the id of the current site.
* <code>component</code> (string) — Optional. Component to use when downloading embedded files.
* <code>componentId</code> (string|number) — Optional. ID to use in conjunction with the component.
* <code>adaptImg</code> (boolean) — Optional, defaults to <code>true</code>. Whether to adapt images to screen width.
* <code>clean</code> (boolean) — Optional, defaults to <code>false</code>. Whether all HTML tags should be removed.
* <code>singleLine</code> (boolean) — Optional, defaults to <code>false</code>. Whether new lines should be removed to display all the text in single line. Only if <code>clean</code> is <code>true</code>.
* <code>maxHeight</code> (number) — Optional. Max height in pixels to render the content box. The minimum accepted value is 50. Using this parameter will force <code>display: block</code> to calculate the height better. If you want to avoid this, use <code>class="inline"</code> at the same time to use <code>display: inline-block</code>.
* <code>fullOnClick</code> (boolean) — Optional, defaults to <code>false</code>. Whether it should open a new page with the full contents on click. Only if <code>maxHeight</code> is set and the content has been collapsed.
* <code>fullTitle</code> (string) — Optional, defaults to <code>"Description"</code>. Title to use in full view.

Example usage:
<syntaxhighlight lang="html+ng2">
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</syntaxhighlight>
====<code>core-link</code>====
Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside <code>core-format-text</code>.

Data that can be passed to the directive:
* <code>capture</code> (boolean) — Optional, defaults to <code>false</code>. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* <code>inApp</code> (boolean) — Optional, defaults to <code>false</code>. Whether to open in an embedded browser within the app or in the system browser.
* <code>autoLogin</code> (string) — Optional, defaults to <code>"check"</code>. If the link should be open with auto-login. Accepts the following values:
** <code>"yes"</code> — Always auto-login.
** <code>"no"</code> — Never auto-login.
** <code>"check"</code> — Auto-login only if it points to the current site.

Example usage:
<syntaxhighlight lang="html+ng2">
<a href="<% cm.url %>" core-link>
</syntaxhighlight>
====<code>core-external-content</code>====
Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside <code>core-format-text</code>.

Data that can be passed to the directive:
* <code>siteId</code> (string) — Optional. Site ID to use. If not defined, it will use the id of the current site.
* <code>component</code> (string) — Optional. Component to use when downloading embedded files.
* <code>componentId</code> (string|number) — Optional. ID to use in conjunction with the component.

Example usage:
<syntaxhighlight lang="html+ng2">
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</syntaxhighlight>
====<code>core-user-link</code>====
Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:
* <code>userId</code> (number) — User id to open the profile.
* <code>courseId</code> (number) — Optional. Course id to show the user info related to that course.

Example usage:
<syntaxhighlight lang="html+ng2">
<a ion-item core-user-link userId="<% userid %>">
</syntaxhighlight>
====<code>core-file</code>====
Component to handle a remote file. It shows the file name, icon (depending on mime type) and a button to download or refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:
* <code>file</code> (object) — The file. Must have a <code>filename</code> property and either <code>fileurl</code> or <code>url</code>.
* <code>component</code> (string) — Optional. Component the file belongs to.
* <code>componentId</code> (string|number) — Optional. ID to use in conjunction with the component.
* <code>canDelete</code> (boolean) — Optional. Whether the file can be deleted.
* <code>alwaysDownload</code> (boolean) — Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* <code>canDownload</code> (boolean) — Optional, defaults to <code>true</code>. Whether file can be downloaded.

Example usage:
<syntaxhighlight lang="html+ng2">
<core-file
[file]="{
fileurl: '<% issue.url %>',
filename: '<% issue.name %>',
timemodified: '<% issue.timemodified %>',
filesize: '<% issue.size %>'
}"
component="mod_certificate"
componentId="<% cm.id %>">
</core-file>
</syntaxhighlight>
====<code>core-download-file</code>====
Directive to allow downloading and opening a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the <code>core-file</code> component since it also displays the state of the file.

Data that can be passed to the directive:
* <code>core-download-file</code> (object) — The file to download.
* <code>component</code> (string) — Optional. Component to link the file to.
* <code>componentId</code> (string|number) — Optional. Component ID to use in conjunction with the component.

Example usage (a button to download a file):
<syntaxhighlight lang="html+ng2">
<ion-button
[core-download-file]="{
fileurl: <% issue.url %>,
timemodified: <% issue.timemodified %>,
filesize: <% issue.size %>
}"
component="mod_certificate"
componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</ion-button>
</syntaxhighlight>
====<code>core-course-download-module-main-file</code>====
Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like <code>mod_resource</code>.

This directive must receive either a <code>module</code> or a <code>moduleId</code>. If no files are provided, it will use <code>module.contents</code>.

Data that can be passed to the directive:
* <code>module</code> (object) — Optional, required if module is not supplied. The module object.
* <code>moduleId</code> (number) — Optional, required if module is not supplied. The module ID.
* <code>courseId</code> (number) — The course ID the module belongs to.
* <code>component</code> (string) — Optional. Component to link the file to.
* <code>componentId</code> (string|number) — Optional, defaults to the same value as <code>moduleId</code>. Component ID to use in conjunction with the component.
* <code>files</code> (object[]) — Optional. List of files of the module. If not provided, uses <code>module.contents</code>.

Example usage:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" core-course-download-module-main-file moduleId="<% cmid %>"
courseId="<% certificate.course %>" component="mod_certificate"
[files]="[{
fileurl: '<% issue.fileurl %>',
filename: '<% issue.filename %>',
timemodified: '<% issue.timemodified %>',
mimetype: '<% issue.mimetype %>',
}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</syntaxhighlight>
====<code>core-navbar-buttons</code>====
Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <code><ion-buttons></code> found in the header.

You can use the <code>[hidden]</code> input to hide all the inner buttons if a certain condition is met.

Example usage:
<syntaxhighlight lang="html+ng2">
<core-navbar-buttons end>
<ion-button (click)="action()">
<ion-icon slot="icon-only" name="funnel"></ion-icon>
</ion-button>
</core-navbar-buttons>
</syntaxhighlight>
You can also use this to add options to the context menu, for example:
<syntaxhighlight lang="html+ng2">
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item
[priority]="500" content="Nice boat" (action)="boatFunction()"
iconAction="boat">
</core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</syntaxhighlight>
===Specific component and directives for plugins===
These are component and directives created specifically for supporting Moodle plugins.
====<code>core-site-plugins-new-content</code>====
Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:
* <code>component</code> (string) — The component of the new content.
* <code>method</code> (string) — The method to get the new content.
* <code>args</code> (object) — The params to get the new content.
* <code>preSets</code> (object) — Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* <code>title</code> (string) — The title to display with the new content. Only if <code>samePage</code> is <code>false</code>.
* <code>samePage</code> (boolean) — Optional, defaults to <code>false</code>. Whether to display the content in same page or open a new one.
* <code>useOtherData</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the arguments for the new <code>get_content</code> call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that doing <code>[useOtherData]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].

Let's see some examples.

A button to go to a new content page:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-new-content
title="<% certificate.name %>" component="mod_certificate"
method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</ion-button>
</syntaxhighlight>
A button to load new content in current page using <code>userid</code> from <code>otherdata</code>:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-new-content
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</ion-button>
</syntaxhighlight>
====<code>core-site-plugins-call-ws</code>====
Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see [[#core-site-plugins-call-ws-new-content|<code>core-site-plugins-call-ws-new-content</code>]].

Data that can be passed to the directive:
* <code>name</code> (string) — The name of the WS to call.
* <code>params</code> (object) — The params for the WS call.
* <code>preSets</code> (object) — Extra options for the WS call: whether to use cache or not, etc.
* <code>useOtherDataForWS</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that <code>[useOtherDataForWS]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].
* <code>confirmMessage</code> (string) — Message to confirm the action when theuser clicks the element. If not supplied, no confirmation will be requested. If supplied but empty, "Are you sure?" will be used.
* <code>showError</code> (boolean) — Optional, defaults to <code>true</code>. Whether to show an error message if the WS call fails. This field was added in 3.5.2.
* <code>successMessage</code> (string) — Message to show on success. If not supplied, no message. If supplied but empty, defaults to "Success".
* <code>goBackOnSuccess</code> (boolean) — Whether to go back if the WS call is successful.
* <code>refreshOnSuccess</code> (boolean) — Whether to refresh the current view if the WS call is successful.
* <code>onSuccess</code> (Function) — A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in 3.5.2.
* <code>onError</code> (Function) — A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in 3.5.2.
* <code>onDone</code> (Function) — A function to call when the WS call finishes (either success or fail). This field was added in 3.5.2.

Let's see some examples.

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
[preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage
refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</ion-button>
</syntaxhighlight>
A button to send some data to the server using cache without confirming, going back on success and using <code>userid</code> from <code>otherdata</code>:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</ion-button>
</syntaxhighlight>
Same as the previous example, but implementing custom JS code to run on success:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
[useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</ion-button>
</syntaxhighlight>
In the JavaScript side, you would do:
<syntaxhighlight lang="javascript">
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</syntaxhighlight>
====<code>core-site-plugins-call-ws-new-content</code>====
Directive to call a WS when the element is clicked and load a new content passing the WS result as arguments. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see [[#core-site-plugins-call-ws|<code>core-site-plugins-call-ws</code>]].

Data that can be passed to the directive:
* <code>name</code> (string) — The name of the WS to call.
* <code>params</code> (object) — The parameters for the WS call.
* <code>preSets</code> (object) — Extra options for the WS call: whether to use cache or not, etc.
* <code>useOtherDataForWS</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that <code>[useOtherDataForWS]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].
* <code>confirmMessage</code> (string) — Message to confirm the action when theuser clicks the element. If not supplied, no confirmation will be requested. If supplied but empty, "Are you sure?" will be used.
* <code>showError</code> (boolean) — Optional, defaults to <code>true</code>. Whether to show an error message if the WS call fails. This field was added in 3.5.2.
* <code>component</code> (string) — The component of the new content.
* <code>method</code> (string) — The method to get the new content.
* <code>args</code> (object) — The parameters to get the new content.
* <code>title</code> (string) — The title to display with the new content. Only if <code>samePage</code> is <code>false</code>.
* <code>samePage</code> (boolean) — Optional, defaults to <code>false</code>. Whether to display the content in the same page or open a new one.
* <code>useOtherData</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the arguments for the new <code>get_content</code> call. The format is the same as in <code>useOtherDataForWS</code>.
* <code>jsData</code> (any) — JS variables to pass to the new page so they can be used in the template or JS. If <code>true</code> is supplied instead of an object, all initial variables from current page will be copied. This field was added in 3.5.2.
* <code>newContentPreSets</code> (object) — Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in 3.6.0.
* <code>onSuccess</code> (Function) — A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in 3.5.2.
* <code>onError</code> (Function) — A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in 3.5.2.
* <code>onDone</code> (Function) — A function to call when the WS call finishes (either success or fail). This field was added in 3.5.2.

Let's see some examples.

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws-new-content
name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}"
[preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage
title="<% certificate.name %>" component="mod_certificate"
method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</ion-button>
</syntaxhighlight>
A button to get some data from the server using cache, without confirm, displaying new content in same page and using <code>userid</code> from <code>otherdata</code>:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws-new-content
name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}"
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}"
samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</ion-button>
</syntaxhighlight>

Same as the previous example, but implementing a custom JS code to run on success:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws-new-content
name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}"
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}"
samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</ion-button>
</syntaxhighlight>
In the JavaScript side, you would do:
<syntaxhighlight lang="javascript">
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</syntaxhighlight>
====<code>core-site-plugins-call-ws-on-load</code>====
Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see [[#core-site-plugins-call-ws|<code>core-site-plugins-call-ws</code>]].
* <code>name</code> (string) — The name of the WS to call.
* <code>params</code> (object) — The parameters for the WS call.
* <code>preSets</code> (object) — Extra options for the WS call: whether to use cache or not, etc.
* <code>useOtherDataForWS</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that <code>[useOtherDataForWS]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].
* <code>onSuccess</code> (Function) — A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in 3.5.2.
* <code>onError</code> (Function) — A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in 3.5.2.
* <code>onDone</code> (Function) — A function to call when the WS call finishes (either success or fail). This field was added in 3.5.2.

Example usage:
<syntaxhighlight lang="html+ng2">
<span core-site-plugins-call-ws-on-load
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
[preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)">
</span>
</syntaxhighlight>
In the JavaScript side, you would do:
<syntaxhighlight lang="javascript">
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</syntaxhighlight>
==Advanced features==
===Display the plugin only if certain conditions are met===
You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the initialisation method (for more info, please see the [[#Initialisation|Initialisation]] section ahead).

All initialisation methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return the following in the initialisation method (only for Moodle site 3.8 and onwards):
<syntaxhighlight lang="php">
return ['disabled' => true];
</syntaxhighlight>
If the Moodle site is older than 3.8, then the initialisation method should return this instead:
<syntaxhighlight lang="php">
return ['javascript' => 'this.HANDLER_DISABLED'];
</syntaxhighlight>
On the other hand, you might want to display a plugin only for certain courses (<code>CoreCourseOptionsDelegate</code>) or only if the user is viewing certain users' profiles (<code>CoreUserDelegate</code>). This can be achieved with the initialisation method too.

In the initialisation method you can return a <code>restrict</code> property with two fields in it: <code>courses</code> and <code>users</code>. If you return a list of courses IDs in this property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.
===Using <code>otherdata</code>===
The values returned by the functions in <code>otherdata</code> are added to a variable so they can be used both in JavaScript and in templates. The <code>otherdata</code> returned by an initialisation call is added to a variable named <code>INIT_OTHERDATA</code>, while the <code>otherdata</code> returned by a <code>get_content</code> WS call is added to a variable named <code>CONTENT_OTHERDATA</code>.

The <code>otherdata</code> returned by an initialisation call will be passed to the JS and template of all the <code>get_content</code> calls in that handler. The <code>otherdata</code> returned by a <code>get_content</code> call will only be passed to the JS and template returned by that <code>get_content</code> call.

This means that, in your JavaScript, you can access and use the data like this:
<syntaxhighlight lang="javascript">
this.CONTENT_OTHERDATA.myVar;
</syntaxhighlight>
And in the template you could use it like this:
<syntaxhighlight lang="html+ng2">
{{ CONTENT_OTHERDATA.myVar }}
</syntaxhighlight>
<code>myVar</code> is the name we put to one of our variables, it can be any name that you want. In the example above, this is the <code>otherdata</code> returned by the PHP method:
<syntaxhighlight lang="php">
['myVar' => 'Initial value']
</syntaxhighlight>
====Example====
In our plugin, we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain Web Service. This can be done using <code>otherdata</code>.

We will return the initial value of the input in the <code>otherdata</code> of our PHP method:
<syntaxhighlight lang="php">
'otherdata' => ['myVar' => 'My initial value'],
</syntaxhighlight>
Then in the template we will use it like this:
<syntaxhighlight lang="html+ng2">
<ion-item text-wrap>
<ion-label position="stacked">{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<ion-button expand="block" color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</ion-button>
</ion-item>
</syntaxhighlight>
In the example above, we are creating an input text and we use <code>[(ngModel)]</code> to use the value in <code>myVar</code> as the initial value and to store the changes in the same <code>myVar</code> variable. This means that the initial value of the input will be "My initial value", and if the user changes the value of the input these changes will be applied to the <code>myVar</code> variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the <code>core-site-plugins-call-ws</code> directive. We use the <code>useOtherDataForWS</code> attribute to specify which variable from <code>otherdata</code> we want to send to our WebService. So if the user enters "A new value" in the input and then clicks the button, it will call the WebService <code>mod_certificate_my_webservice</code> and will send as a parameter <code>['myVar' => 'A new value']</code>.

We can also achieve the same result using the <code>params</code> attribute of the <code>core-site-plugins-call-ws</code> directive instead of using <code>useOtherDataForWS</code>:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" color="light" core-site-plugins-call-ws
name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</ion-button>
</syntaxhighlight>
The Web Service call will be exactly the same with both versions.

Notice that this example could be done without using <code>otherdata</code> too, using the <code>form</code> input of the <code>core-site-plugins-call-ws</code> directive.
===Running JS code after a content template has loaded===
When you return JavaScript code from a handler function using the <code>javascript</code> array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use <code>setTimeout</code> to call it. For example:
<syntaxhighlight lang="php">
return [
'template' => [
// ...
],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => [],
];
</syntaxhighlight>
Notice that if you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an initialisation template, so that it does not get loaded again with each page of content.
===JS functions visible in the templates===
The app provides some JavaScript functions that can be used from the templates to update, refresh or view content. These are the functions:
* <code>openContent(title: string, args: any, component?: string, method?: string)</code> — Open a new page to display some new content. You need to specify the <code>title</code> of the new page and the <code>args</code> to send to the method. If <code>component</code> and <code>method</code> aren't provided, it will use the same as in the current page.
* <code>refreshContent(showSpinner = true)</code> — Refresh the current content. By default, it will display a spinner while refreshing. If you don't want it to be displayed, you should pass <code>false</code> as a parameter.
* <code>updateContent(args: any, component?: string, method?: string)</code> — Refresh the current content using different parameters. You need to specify the <code>args</code> to send to the method. If <code>component</code> and <code>method</code> aren't provided, it will use the same as in the current page.
====Examples====
=====Group selector=====
Imagine we have an activity that uses groups and we want to let the user select which group they want to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down, we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's <code>ngModel</code>.
======Using plain HTML======
We need to add a <code>selected</code> attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:
<syntaxhighlight lang="php">
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = [
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups,
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
];
</syntaxhighlight>
In the code above, we're retrieving the groups the user can see and then we're adding a <code>selected</code> boolean to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:
<syntaxhighlight lang="html+handlebars">
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</syntaxhighlight>
The <code>ionChange</code> function will be called every time the user selects a different group with the drop down. We're using the <code>updateContent</code> function to update the current view using the new group. <code>$event</code> is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.
======Using <code>ngModel</code>======
<code>ngModel</code> is an Angular directive that allows storing the value of a certain input or select in a JavaScript variable, and also the opposite way: tell the input or select which value to set. The main problem is that we cannot initialise a JavaScript variable from the template, so we'll use <code>otherdata</code>.

In the PHP function we'll return the group that needs to be selected in the <code>otherdata</code> array:
<syntaxhighlight lang="php">
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

// ...

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'otherdata' => [
'group' => $groupid,
],
];
</syntaxhighlight>
In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the group id in the <code>otherdata</code> array. As it's explained in the [[#Using_otherdata|Using <code>otherdata</code>]] section, this <code>otherdata</code> is visible in the templates inside a variable named <code>CONTENT_OTHERDATA</code>. So in the template we'll use this variable like this:
<syntaxhighlight lang="html+handlebars">
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group"
(ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})"
interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</syntaxhighlight>
===Use the rich text editor===
The rich text editor included in the app requires a <code>FormControl</code> to work. You can use the <code>FormBuilder</code> library to create this control (or to create a whole <cide>FormGroup if you prefer).

With the following JavaScript you'll be able to create a <code>FormControl</code>:
<syntaxhighlight lang="javascript">
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</syntaxhighlight>
In the example above we're using a value returned in <code>OTHERDATA</code> as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:
<syntaxhighlight lang="html+ng2">
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer">
</core-rich-text-editor>
</ion-item>
</syntaxhighlight>
Finally, there are several ways to send the value in the rich text editor to a Web Service to save it. This is one of the simplest options:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ...
</syntaxhighlight>
As you can see, we're passing the value of the rich text editor as a parameter to our Web Service.
===Initialisation===
All handlers can specify an <code>init</code> method in the <code>mobile.php</code> file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the <code>tool_mobile_get_content</code> Web Service with the initialisation method. This WS call will only receive the default arguments.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the <code>mobile.php</code> data.

The templates returned by this method will be added to a <code>INIT_TEMPLATES</code> variable that will be passed to all the JavaScript code of that handler. This means that the JavaScript returned by the initialisation method or the main method can access any of the templates HTML like this:
<syntaxhighlight lang="javascript">
this.INIT_TEMPLATES['main'];
</syntaxhighlight>
In this case, <code>main</code> is the ID of the template we want to use.

The same happens with the <code>otherdata</code> returned by the initialisation method, it is added to an <code>INIT_OTHERDATA</code> variable.

The <code>restrict</code> field returned by this call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate <code>CoreCourseOptionsDelegate</code> and you return a list of course ids in <code>restrict.courses</code>, then your handler will only be enabled in the courses you returned. This only applies to the default handlers, if you register your own handler using the JavaScript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this initialisation JavaScript code, all the properties of that object will be passed to all the JavaScript code of that handler so you can use them when the code is run. For example, if your JavaScript code does something like this:
<syntaxhighlight lang="javascript">
var result = {
MyAddonClass: new MyAddonClass()
};

result;
</syntaxhighlight>
Then, for the rest of JavaScript code of your handler (for example, the main method) you can use this variable like this:
<syntaxhighlight lang="javascript">
this.MyAddonClass
</syntaxhighlight>
====Examples====
=====Module link handler=====
A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using an initialisation JavaScript:
<syntaxhighlight lang="javascript">
class AddonModCertificateModuleLinkHandler extends this.CoreContentLinksModuleIndexHandler {

constructor() {
super('mmaModCertificate', 'certificate');

this.name = 'AddonModCertificateLinkHandler';
}

}

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</syntaxhighlight>
=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<syntaxhighlight lang="javascript">
class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

constructor() {
super();

this.pattern = RegExp('\/mod\/foo\/specialpage.php');
}

}
</syntaxhighlight>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority; the handler with the highest priority will be used.

All default handlers have a priority of 0, so 1 or higher will override the default.
<syntaxhighlight lang="javascript">
class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

constructor() {
super();

this.priority = 1;
}

}
</syntaxhighlight>
======Multiple actions======
Once a link has been matched, the handler's <code>getActions()</code> method determines what the link should do. This method has access to the URL and its parameters.

Different actions can be returned depending on different conditions.
<syntaxhighlight lang="javascript">
class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

getActions(siteIds, url, params) {
return [
{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [
// ...
],
},
{
// ...
},
];
}

}
</syntaxhighlight>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first valid action will be used to open the link.

If your handler is matched with a link, but a condition assessed in the <code>getActions()</code> method means you want to revert to the next highest priorty handler, you can invalidate your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing <code>/mod/foo/</code>, and force those with an id parameter that's not in the <code>supportedModFoos</code> array to open in the user's browser, rather than the app.
<syntaxhighlight lang="javascript">
const that = this;
const supportedModFoos = [...];

class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

constructor() {
super();

this.pattern = new RegExp('\/mod\/foo\/');
this.name = 'AddonModFooLinkHandler';
this.priority = 1;
}

getActions(siteIds, url, params) {
const action = {
action() {
that.CoreUtilsProvider.openInBrowser(url);
},
};

if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}

return [action];
}

}

this.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</syntaxhighlight>
=====Module prefetch handler=====
The <code>CoreCourseModuleDelegate</code> handler allows you to define a list of offline functions to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using offline functions.

Here’s an example on how to create a prefetch handler using the initialisation JS:
<syntaxhighlight lang="javascript">
// Create a class that extends from CoreCourseActivityPrefetchHandlerBase.
class AddonModCertificateModulePrefetchHandler extends CoreCourseActivityPrefetchHandlerBase {

constructor() {
super();

this.name = 'AddonModCertificateModulePrefetchHandler';
this.modName = 'certificate';

// This must match the plugin identifier from db/mobile.php,
// otherwise the download link in the context menu will not update correctly.
this.component = 'mod_certificate';
this.updatesNames = /^configuration$|^.*files$/;
}

// Override the prefetch call.
prefetch(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
}

}

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</syntaxhighlight>
One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same <code>cmid</code>. The app will not automatically work with this situation — it will call the offline function with the standard arguments only — so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function, the rest of the code is as above) where there are multiple values of a custom <code>section</code> parameter for the mobile function <code>mobile_document_view</code>:
<syntaxhighlight lang="javascript">
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</syntaxhighlight>
=====Single activity course format=====
In the following example, the value of <code>INIT_TEMPLATES['main']</code> is:
<syntaxhighlight lang="html+ng2">
<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>
</syntaxhighlight>
This template is returned by the initialisation method. And this is the JavaScript code returned:
<syntaxhighlight lang="javascript">
var that = this;

class AddonSingleActivityFormatComponent {

constructor() {
this.data = {};
}

ngOnChanges(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
}

doRefresh(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
}

}

class AddonSingleActivityFormatHandler {

constructor() {
this.name = 'singleactivity';
}

isEnabled() {
return true;
}

canViewAllSections() {
return false;
}

getCourseTitle(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || '';
}

displayEnableDownload() {
return false;
}

displaySectionSelector() {
return false;
}

getCourseFormatComponent() {
return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES['main'], AddonSingleActivityFormatComponent);
}

}

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</syntaxhighlight>
===Using the JavaScript API===
The JavaScript API is only supported by the delegates specified in the [[#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] section. This API allows you to override any of the functions of the default handler.

The <code>method</code> specified in a handler registered in the <code>CoreUserProfileFieldDelegate</code> will be called immediately after the initialisation method, and the JavaScript returned by this method will be run. If this JavaScript code returns an object with certain functions, these functions will override the ones in the default handler.

For example, if the JavaScript returned by the method returns something like this:
<syntaxhighlight lang="javascript">
var result = {
getData: function(field, signup, registerAuth, formValues) {
// ...
}
};
result;
</syntaxhighlight>
The the <code>getData</code> function of the default handler will be overridden by the returned <code>getData</code> function.

The default handler for <code>CoreUserProfileFieldDelegate</code> only has 2 functions: <code>getComponent</code> and <code>getData</code>. In addition, the JavaScript code can return an extra function named <code>componentInit</code> that will be executed when the component returned by <code>getComponent</code> is initialised.

Here’s an example on how to support the text user profile field using this API:
<syntaxhighlight lang="javascript">
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = 'profile_field_' + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || '';
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? 'password' : 'text';

var formData = {
value: this.field.defaultdata,
disabled: this.disabled,
};

this.form.addControl(this.field.modelName,
that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = 'profile_field_' + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name]),
};
}
};

result;
</syntaxhighlight>
===Translate dynamic strings===
If you wish to have an element that displays a localised string based on value from your template you can doing something like:
<syntaxhighlight lang="html+handlebars">
<ion-card>
<ion-card-content>
{{ 'plugin.mod_myactivity.<% status %>' | translate }}
</ion-card-content>
</ion-card>
</syntaxhighlight>
This could save you from having to write something like when only one value should be displayed:
<syntaxhighlight lang="html+handlebars">
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</syntaxhighlight>
===Using strings with dates===
If you have a string that you wish to pass a formatted date, for example in the Moodle language file you have:
<syntaxhighlight lang="php">
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</syntaxhighlight>
You can localise the string correctly in your template using something like the following:
<syntaxhighlight lang="html+handlebars">
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</syntaxhighlight>
A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, whereas Unix timestamps are in seconds.
===Support push notification clicks===
If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a <code>contexturl</code> in your notification. When the notification is clicked, the app will try to open the <code>contexturl</code>.

Please notice that the <code>contexturl</code> will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a <code>customdata</code> array that contains an <code>appurl</code> property:
<syntaxhighlight lang="php">
$notification->customdata = [
'appurl' => $myurl->out(),
];
</syntaxhighlight>
In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[#Advanced_link_handler|creating an advanced link handler]], but you'll have to use <code>CorePushNotificationsDelegate</code> and your handler will have to implement the properties and functions defined in the [https://github.com/moodlehq/moodleapp/blob/master/src/core/features/pushnotifications/services/push-delegate.ts#L27 CorePushNotificationsClickHandler] interface.
===Implement a module similar to mod_label===
In Moodle 3.8 or higher, if your plugin doesn't support <code>FEATURE_NO_VIEW_LINK</code> and you don't specify a <code>coursepagemethod</code> then the module will only display the module description in the course page and it won't be clickable in the app, just like <code>mod_label</code>. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in <code>displaydata</code>).

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the <code>coursepagemethod</code> property in <code>mobile.php</code>. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only plain HTML.

If you don't want your module to be clickable then you just need to remove <code>method</code> from <code>mobile.php</code>. With these 2 changes you can have a module that behaves like <code>mod_label</code> in the app.
===Use Ionic navigation lifecycle functions===
Ionic let pages define some functions that will be called when certain navigation lifecycle events happen. For more info about these functions, see [https://ionicframework.com/docs/api/router-outlet Ionic's documentation].

You can define these functions in your plugin javascript:
<syntaxhighlight lang="javascript">
this.ionViewWillLeave = function() {
// ...
};</syntaxhighlight>
In addition to that, you can also implement <code>canLeave</code> to use Angular route guards:
<syntaxhighlight lang="javascript">
this.canLeave = function() {
// ...
};</syntaxhighlight>
So for example you can make your plugin ask for confirmation if the user tries to leave the page when he has some unsaved data.
===Module plugins: dynamically determine if a feature is supported===
In Moodle you can specify if your plugin supports a certain feature, like <code>FEATURE_NO_VIEW_LINK</code>. If your plugin will always support or not a certain feature, then you can use the <code>supportedfeatures</code> property in <code>mobile.php</code> to specify it ([[#Options_only_for_CoreCourseModuleDelegate|see more documentation about this]]). But if you need to calculate it dynamically then you will have to create a function to calculate it.

This can be achieved using the initialisation method (for more info, please see the [[#Initialisation|Initialisation]] section above). The JavaScript returned by your initialisation method will need to define a function named <code>supportsFeature</code> that will receive the name of the feature:
<syntaxhighlight lang="javascript">
var result = {
supportsFeature: function(featureName) {
// ...
}
};
result;
</syntaxhighlight>
Currently the app only uses <code>FEATURE_MOD_ARCHETYPE</code> and <code>FEATURE_NO_VIEW_LINK</code>.
== Testing ==
You can also write automated tests for your plugin using Behat, you can read more about it on the [[Acceptance testing for the Moodle App]] page.
== Upgrading plugins from an older version ==
If you added mobile support to your plugin for the Ionic 3 version of the app (previous to the 3.9.5 release), you will probably need to make some changes to make it compatible with Ionic 5.

Learn more at the [[Moodle App Plugins Upgrade Guide]].
==Troubleshooting==
=== Invalid response received ===
You might receive this error when using the <code>core-site-plugins-call-ws</code> directive or similar. By default, the app expects all Web Service calls to return an object, if your Web Service returns another type (string, boolean, etc.) then you need to specify it using the <code>preSets</code> attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:
<syntaxhighlight lang="html+ng2">
[preSets]="{typeExpected: 'boolean'}"
</syntaxhighlight>
In a similar way, if your Web Service returns <code>null</code> you need to tell the app not to expect any result using <code>preSets</code>:
<syntaxhighlight lang="html+ng2">
[preSets]="{responseExpected: false}"
</syntaxhighlight>
=== Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS ===
Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, <code>ion-radio</code>, <code>ion-checkbox</code> and <code>ion-select</code> don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the Web Service.

There are 2 workarounds to fix this problem.
==== Sending the data manually ====
The first solution is to send the missing params manually using the <code>params</code> property. We will use <code>ngModel</code> to store the input value in a variable, and this variable will be passed to the parameters. Please notice that <code>ngModel</code> requires the element to have a name, so if you add <code>ngModel</code> to a certain element you need to add a name too.

For example, if you have a template like this:
<syntaxhighlight lang="html+ng2">
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<ion-button expand="block" type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</ion-button>
</syntaxhighlight>
Then you should modify it like this:
<syntaxhighlight lang="html+ng2">
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<ion-button expand="block" type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</ion-button>
</syntaxhighlight>
Basically, you need to add <code>ngModel</code> to the affected element (in this case, the <code>radio-group</code>). You can put whatever name you want as the value, we used "responses". With this, every time the user selects a radio button the value will be stored in a variable called "responses". Then, in the button we are passing this variable to the parameters of the Web Service.

Please notice that the <code>form</code> attribute has priority over <code>params</code>, so if you have an input with <code>name="responses"</code> it will override what you're manually passing to <code>params</code>.
==== Using a hidden input ====
Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use <code>ngModel</code> to synchronise your radio/checkbox/select with the new hidden input. Please notice that <code>ngModel</code> requires the element to have a name, so if you add <code>ngModel</code> to a certain element you need to add a name too.

For example, if you have a radio button like this:
<syntaxhighlight lang="html+ng2">
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</syntaxhighlight>
Then you should modify it like this:
<syntaxhighlight lang="html+ng2">
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</syntaxhighlight>
In the example above, we're using a variable called "responses" to synchronise the data between the <code>radio-group</code> and the hidden input. You can use whatever name you want.
=== I can't return an object or array in <code>otherdata</code> ===
If you try to return an object or an array in any field inside <code>otherdata</code>, the Web Service call will fail with the following error:
<syntaxhighlight lang="text">
Scalar type expected, array or object received
</syntaxhighlight>
Each field in <code>otherdata</code> must be a string, number or boolean; it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:
<syntaxhighlight lang="php">
'otherdata' => ['data' => json_encode($data)],
</syntaxhighlight>
The app will automatically parse this JSON and convert it back into an array or object.
==Examples==
===Accepting dynamic names in a Web Service===
We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new Web Service that we have created.

The first issue we find is that the Web Service needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the <code>_parameters()</code> function of our new Web Service, we will add this parameter:
<syntaxhighlight lang="php">
'data' => new external_multiple_structure(
new external_single_structure(
[
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
]
),
'The data to be saved', VALUE_DEFAULT, []
)
</syntaxhighlight>
Now we need to adapt our form to send the data as the Web Service requires it. In our template, we have a button with the <code>core-site-plugins-call-ws</code> directive that will send the form data to our Web Service. To make this work we will have to pass the parameters manually, without using the <code>form</code> attribute, because we need to format the data before it is sent.

Since we will send the parameters manually and we want it all to be sent in the same array, we will use <code>ngModel</code> to store the input data into a variable that we'll call <code>data</code>, but you can use the name you want. This variable will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:
<syntaxhighlight lang="javascript">
{a1: 'My answer'}
</syntaxhighlight>
So we need to add <code>ngModel</code> to all the inputs whose values need to be sent to the <code>data</code> WS param. Please notice that <code>ngModel</code> requires the element to have a name, so if you add <code>ngModel</code> to a certain element you need to add a name too. For example:
<syntaxhighlight lang="html+ng2">
<ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']">
</syntaxhighlight>
As you can see, we're using <code>CONTENT_OTHERDATA</code> to store the data. We do it like this because we'll use <code>otherdata</code> to initialise the form, setting the values the user has already stored. If you don't need to initialise the form, then you can use the <code>dataObject</code> variable, an empty object that the mobile app creates for you:
<syntaxhighlight lang="html+ng2">
[(ngModel)]="dataObject['<% name %>']"
</syntaxhighlight>
The app has a function that allows you to convert this data object into an array like the one the WS expects: <code>objectToArrayOfObjects</code>. So in our button we'll use this function to format the data before it's sent:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</syntaxhighlight>
As you can see in the example above, we're specifying that the keys of the <code>data</code> object need to be stored in a property called "name", and the values need to be stored in a property called "value". If your Web Service expects different names you need to change the parameters of the <code>objectToArrayOfObjects</code> function.

If you open your plugin now in the app it will display an error in the JavaScript console. The reason is that the <code>data</code> variable doesn't exist inside <code>CONTENT_OTHERDATA</code>. As it is explained in previous sections, <code>CONTENT_OTHERDATA</code> holds the data that you return in <code>otherdata</code> for your method. We'll use <code>otherdata</code> to initialise the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialise the <code>data</code> object as an empty object. Please remember that we cannot return arrays or objects in <code>otherdata</code>, so we'll return a JSON string.
<syntaxhighlight lang="php">
'otherdata' => ['data' => '{}'],
</syntaxhighlight>
With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:
<syntaxhighlight lang="php">
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: ['a1' => 'My value'].

// ...

'otherdata' => ['data' => json_encode($userdata)],
</syntaxhighlight>
Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our Web Service in array format.
==Moodle plugins with mobile support==
* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].
See the complete list in [https://moodle.org/plugins/browse.php?list=award&id=6 the plugins database] (it may contain some outdated plugins).
=== Mobile app support award ===
If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email at [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory.
[[Category:Mobile]]
[[Category:Moodle App Ionic 5]]

Moodle App Plugins Development Guide

2022-04-25T06:20:27Z

Dpalou: Specify all the delegates that support ptrenabled option.

{{Moodle App (Ionic 5)}}
If you want to add mobile support to your Moodle plugin, you can achieve it by extending different areas of the app using ''just PHP server side code'' and providing templates written with [https://ionicframework.com/docs/components Ionic] and custom components.

You will have to:
# Create a <code>db/mobile.php</code> file in your plugin. In this file, you will be able to indicate which areas of the app you want to extend. For example, adding a new option in the main menu, implementing support for a new activity module, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered as html. This html should use Ionic components so that it looks native, but it can be generated using mustache templates.

Let’s clarify some points:
* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function <code>tool_mobile_get_content</code>.
* As arguments of your functions you will always receive the <code>userid</code>, some relevant details of the app (like the app version or the current language in the app), and some specific data depending on the type of plugin (<code>courseid</code>, <code>cmid</code>, ...).
* The mobile app also implements a list of custom Ionic components and directives that provide dynamic behaviour; like indicating that you are linking a file that can be downloaded, allowing a transition to new pages into the app calling a specific function in the server, submitting form data to the server, etc.

==Getting started==
If you only want to write a plugin, it is not necessary that you set up your environment to work with the Moodle App. In fact, you don't even need to compile it. You can just [[Using the Moodle App in a browser|use a Chromium-based browser]] to add mobile support to your plugins!

You can use the app from one of the hosted versions on [https://master.apps.moodledemo.net master.apps.moodledemo.net] (the latest stable version) and [https://integration.apps.moodledemo.net integration.apps.moodledemo.net] (the latest development version). If you need any specific environment (hosted versions are deployed with a ''production'' environment), you can also use [[Moodle App Docker Images|Docker images]]. And if you need to test your plugin in a native device, you can always use [https://download.moodle.org/mobile Moodle HQ's application].

This should suffice for developing plugins. However, if you are working on advanced functionality and you need to run the application from the source code, you can find more information in the [[Moodle App Development Guide]].
===Development workflow===
Before getting into the specifics of your plugin, we recommend that you start adding a simple "Hello World" button in the app to see that everything works properly.

Let's say your plugin is called <code>local_hello</code>, you can start by adding the following files:

<code>db/mobile.php</code>
<syntaxhighlight lang="php">
<?php

$addons = [
'local_hello' => [
'handlers' => [
'hello' => [
'delegate' => 'CoreMainMenuDelegate',
'method' => 'view_hello',
'displaydata' => [
'title' => 'hello',
'icon' => 'earth',
],
],
],
'lang' => [
['hello', 'local_hello'],
],
],
];
</syntaxhighlight>
<code>classes/output/mobile.php</code>
<syntaxhighlight lang="php">
<?php

namespace local_hello\output;

defined('MOODLE_INTERNAL') || die();

class mobile {

public static function view_hello() {
return [
'templates' => [
[
'id' => 'main',
'html' => '<h1 class="text-center">{{ "plugin.local_hello.hello" | translate }}</h1>',
],
],
];
}

}
</syntaxhighlight>
<code>lang/en/local_hello.php</code>
<syntaxhighlight lang="php">
<?php

$string['hello'] = 'Hello World';
</syntaxhighlight>
Once you've done that, try logging into your site in the app and you should see a new button in the main menu or more menu (depending on the device) saying "Hello World". If you press this button, you should see a page saying "Hello World!".

Congratualtions, you have written your first Moodle plugin with moodle support!

You can read the rest of this page to learn more about mobile plugins and start working on your plugin. Here's some things to keep in mind:
* If you change the <code>mobile.php</code> file, you will have to refresh the browser. And remember to [https://developer.chrome.com/docs/devtools/network/reference/#disable-cache disable the network cache].
* If you change an existing template or function, you won’t have to refresh the browser. In most cases, doing a PTR (Pull To Refresh) in the page that displays the template will suffice.
* If any of these doesn't show your changes, you may need to [https://docs.moodle.org/311/en/Developer_tools#Purge_all_caches purge all caches] to avoid problems with the auto-loading cache.
* Ultimately, if that doesn't work either, you may have to log out from the site and log in again. If any changes affect plugin installation, you may also need to increase the version in your plugin's <code>version.php</code> file and upgrade it in the site.
==Types of plugins==
There are 3 types of plugins:
===Templates generated and downloaded when the user opens the plugins===
[[File:Templates_downloaded_when_requested.png|thumb]]
With this type of plugin, the template of your plugin will be generated and downloaded when the user opens the plugin in the app. This means that your function will receive some context parameters. For example, if you're developing a course module plugin you will receive the <code>courseid</code> and the <code>cmid</code> (course module ID). You can see the list of delegates that support this type of plugin in the [[#Delegates|Delegates]] section.
===Templates downloaded on login and rendered using JS data===
[[File:Templates_downloaded_on_login.png|thumb]]
With this type of plugin, the template for your plugin will be downloaded when the user logs in into the app and will be stored in the device. This means that your function will not receive any context parameters, and you need to return a generic template that will be built with JS data like the ones in the Moodle App. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[#Delegates|Delegates]] section.
===Pure JavaScript plugins===
You can always implement the whole plugin yourself using JavaScript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[#Delegates|Delegates]] section.
==Step by step example==
In this example, we are going to update an existing plugin, the [https://github.com/mdjnelson/moodle-mod_certificate Certificate activity module], that previously used a [[Moodle Mobile 2 (Ionic 1) Remote add-ons|Remote add-on]] (a legacy approach to implement mobile plugins).

This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.
===Step 1. Update the <code>db/mobile.php</code> file===
In this case, we are updating an existing file. For new plugins, you should create this new file.
<syntaxhighlight lang="php">
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</syntaxhighlight>
;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields). In this case, we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the [[#Delegates|Delegates]] section for all the possible options.

; Method:
: This is the method in the Moodle <code>\{component-name}\output\mobile</code> class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the <code>mobile.php</code> file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current <code>userid</code> (and <code>courseid</code> when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently <code>userid</code> and <code>courseid</code>).
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the <code>files</code> array).
: Note that if your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a <code>page</code> parameter in addition to the usual <code>cmid</code>, <code>courseid</code>, and <code>userid</code>) then the app will not know which additional parameters to supply. In this case, do not list the function in <code>offlinefunctions</code>; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here, like <code>['cancel', 'moodle']</code>. If you do this, be warned that in the app you will then need to refer to that string as <code><nowiki>{{ 'plugin.myplugin.cancel' | translate }}</nowiki></code> (not <code><nowiki>{{ 'plugin.moodle.cancel' | translate }}</nowiki></code>).
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.
There are additional attributes supported by the <code>mobile.php</code> list, you can find about them in the [[#Mobile.php_supported_options|Mobile.php supported options]] section.
===Step 2. Creating the main function===
The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem <code>classes/output</code> directory, the name of the class must be <code>mobile</code>.

For this example, the namespace name will be <code>mod_certificate\output</code>.

<code>mod/certificate/classes/output/mobile.php</code>
<syntaxhighlight lang="php">
<?php

namespace mod_certificate\output;

use context_module;
use mod_certificate_external;

class mobile {

/**
* Returns the certificate course view for the mobile app.
*
* @param array $args Arguments from tool_mobile_get_content WS.
*
* @return array HTML, JS and other data.
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid, false, $cm, true, true);

$context = \context_module::instance($cm->id);

require_capability('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', ['id' => $cm->instance]);

// Get certificates from external (taking care of exceptions).
try {
$issued = \mod_certificate_external::issue_certificate($cm->instance);
$certificates = \mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = [];
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
[$certificate->intro, $certificate->introformat] =
external_format_text($certificate->intro, $certificate->introformat, $context->id, 'mod_certificate', 'intro');
$data = [
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid,
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</syntaxhighlight>
;Function declaration:
: The function name is the same as the one used in the <code>mobile.php</code> file (<code>method</code> field). There is only one argument, <code>$args</code>, which is an array containing all the information sent by the mobile app (the <code>courseid</code>, <code>userid</code>, <code>appid</code>, <code>appversionname</code>, <code>appversioncode</code>, <code>applang</code>, <code>appcustomurlscheme</code>, ...).

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a <code>view.php</code> script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

; Function return:
* <code>templates</code> — The rendered template (notice that we could return more than one template, but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some JavaScript code.
* <code>javascript</code> — Empty, because we don’t need any in this case.
* <code>otherdata</code> — Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way data-binding in the template.
* <code>files</code> — A list of files that the app should be able to download (for offline usage mostly).
===Step 3. Creating the template for the main function===
This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic, together with directives and components specific to the Moodle App.

All the HTML elements starting with <code>ion-</code> are ionic components. Most of the time, the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML elements starting with <code>core-</code> are custom components of the Moodle App.

<code>mod/certificate/templates/mobile_view_page.mustache</code>
<syntaxhighlight lang="html+handlebars">
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>">
</core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<ion-button expand="block" color="light" core-site-plugins-new-content title="<% certificate.name %>"
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</ion-button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<ion-button expand="block" core-course-download-module-main-file moduleId="<% cmid %>"
courseId="<% certificate.course %>" component="mod_certificate"
[files]="[{
fileurl: '<% issue.fileurl %>',
filename: '<% issue.filename %>',
timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>',
}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate"
[params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}">
</span>
</ion-list>
</div>
</syntaxhighlight>
In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code>core-course-module-description</code>, which is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.

The following line using the <code>translate</code> filter indicates that the app will translate the <code>summaryofattempts</code> string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has the following format:
<syntaxhighlight lang="text">
plugin.{plugin-identifier}.{string-id}
</syntaxhighlight>
Where <code>{plugin-identifier}</code> is taken from <code>mobile.php</code> and <code>{string-id}</code> must be indicated in the <code>lang</code> field in <code>mobile.php</code>.

Then, we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the <code>mobile_issues_view</code> function in the <code>mod_certificate</code> component; passing as arguments the <code>cmid</code> and <code>courseid</code>. The content returned by this function will be displayed in a new page (read the following section to see the code of this new page).

Just after this button, we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available offline.

Finally, just before the <code>ion-list</code> is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call a Web Service function in the server, in this case we are calling the <code>mod_certificate_view_certificate</code> that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.
===Step 4. Adding an additional page===
Add the following method to <code>mod/certificate/classes/output/mobile.php</code>:
<syntaxhighlight lang="php">
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS.
*
* @return array HTML, JS and other data.
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid, false, $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', ['id' => $cm->instance]);

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = [];
}

$data = ['issues' => $issues];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</syntaxhighlight>
This method for the new page was added just after <code>mobile_course_view</code>, the code is quite similar: checks the capabilities, retrieves the information required for the template, and returns the template rendered.

The code of the mustache template is also very simple.

<code>mod/certificate/templates/mobile_view_issues.mustache</code>
<syntaxhighlight lang="html+handlebars">
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</syntaxhighlight>
As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an Ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter <code>coreToLocaleString</code>). We are also displaying the grade displayed in the certificate (if any).
===Step 5. Plugin webservices, if included===
If your plugin uses its own web services, they will also need to be enabled for mobile access in your <code>db/services.php</code> file.

The following line should be included in each webservice definition:
<syntaxhighlight lang="php">
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
</syntaxhighlight>
<code>mod/certificate/db/services.php</code>
<syntaxhighlight lang="php">
<?php

$functions = [
'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</syntaxhighlight>
==Mobile.php supported options==
In the previous section, we learned about some of the existing options for handlers configuration. This is the full list of supported options.
===Common options===
* <code>delegate</code> (mandatory) — Name of the delegate to register the handler in.
* <code>method</code> (mandatory) — The method to call to retrieve the main page content.
* <code>init</code> (optional) — A method to call to retrieve the initialisation JS and the restrictions to apply to the whole handler. It can also return templates that can be used from JavaScript. You can learn more about this in the [[#Initialisation|Initialisation]] section.
* <code>restricttocurrentuser</code> (optional) — Only used if the delegate has a <code>isEnabledForUser</code> function. If true, the handler will only be shown for the current user. For more info about displaying the plugin only for certain users, please see [[#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* <code>restricttoenrolledcourses</code> (optional) — Only used if the delegate has a <code>isEnabledForCourse</code> function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* <code>styles</code> (optional) — An array with two properties: <code>url</code> and <code>version</code>. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* <code>moodlecomponent</code> (optional) — If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be <code>local_whatever</code>, but in <code>moodlecomponent</code> you can specify that this handler will implement <code>format_whatever</code> or <code>mod_whatever</code>. This property was introduced in the version 3.6.1 of the app.
===Options only for CoreMainMenuDelegate ===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the More tab, they cannot be displayed as tabs in the bottom bar.
* <code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreMainMenuHomeDelegate ===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
* <code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreCourseOptionsDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
* <code>ismenuhandler</code> (optional) — Supported from the 3.7.1 version of the app. Set it to <code>true</code> if you want your plugin to be displayed in the contextual menu of the course instead of in the top tabs. The contextual menu is displayed when you click in the 3-dots button at the top right of the course.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreCourseModuleDelegate===
* <code>displaydata</code> (mandatory):
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>method</code> (optional) — The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* <code>offlinefunctions</code> (optional) — List of functions to call when prefetching the module. It can be a <code>get_content</code> method or a WS. You can filter the params received by the WS. By default, WS will receive these params: <code>courseid</code>, <code>cmid</code>, <code>userid</code>. Other valid values that will be added if they are present in the list of params: <code>courseids</code> (it will receive a list with the courses the user is enrolled in), <code>{component}id</code> (For example, <code>certificateid</code>).
* <code>downloadbutton</code> (optional) — Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* <code>isresource</code> (optional) — Whether the module is a resource or an activity. Only used if there is any offline function. If your module relies on the <code>contents</code> field, then it should be <code>true</code>.
* <code>updatesnames</code> (optional) — Only used if there is any offline function. A regular expression to check if there's any update in the module. It will be compared to the result of <code>core_course_check_updates</code>.
* <code>displayopeninbrowser</code> (optional) — Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: <code>this.displayOpenInBrowser = false;</code>. Supported from the 3.6 version of the app.
* <code>displaydescription</code> (optional) — Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: <code>this.displayDescription = false;</code>. Supported from the 3.6 version of the app.
* <code>displayrefresh</code> (optional) — Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: <code>this.displayRefresh = false;</code>. Supported from the 3.6 version of the app.
* <code>displayprefetch</code> (optional) — Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: <code>this.displayPrefetch = false;</code>. Supported from the 3.6 version of the app.
* <code>displaysize</code> (optional) — Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: <code>this.displaySize = false;</code>. Supported from the 3.6 version of the app.
* <code>supportedfeatures</code> (optional) — It can be used to specify the supported features of the plugin. Currently the app only uses <code>FEATURE_MOD_ARCHETYPE</code> and <code>FEATURE_NO_VIEW_LINK</code>. It should be an array with features as keys (For example, <code>[FEATURE_NO_VIEW_LINK => true</code>). If you need to calculate this dynamically please see [[#Module_plugins:_dynamically_determine_if_a_feature_is_supported|Module plugins: dynamically determine if a feature is supported]]. Supported from the 3.6 version of the app.
* <code>coursepagemethod</code> (optional) — If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML. Supported from the 3.8 version of the app.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreCourseFormatDelegate===
* <code>canviewallsections</code> (optional) — Whether the course format allows seeing all sections in a single page. Defaults to <code>true</code>.
* <code>displayenabledownload</code> (optional) — Whether the option to enable section/module download should be displayed. Defaults to <code>true</code>.
* <code>displaysectionselector</code> (optional) — Whether the default section selector should be displayed. Defaults to <code>true</code>.
===Options only for CoreUserDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>type</code> — The type of the addon. The values accepted are <code>'newpage'</code> (default) and <code>'communication'</code>.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreSettingsDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
** <code>class</code> — A CSS class.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for AddonMessageOutputDelegate===
* <code>displaydata</code> (mandatory):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section.
** <code>icon</code> — The name of an ionic icon. Valid strings can be found here: https://ionic.io/ionicons.
* <code>priority</code> (optional) — Priority of the handler. Higher priority is displayed first.
*<code>ptrenabled</code> (optional) — Whether to enable pull-to-refresh gesture to refresh page content.
===Options only for CoreBlockDelegate===
* <code>displaydata</code> (optional):
** <code>title</code> — A language string identifier that was included in the <code>lang</code> section. If this is not supplied, it will default to <code>'plugins.block_{block-name}.pluginname'</code>, where <code>{block-name}</code> is the name of the block.
** <code>class</code> — A CSS class. If this is not supplied, it will default to <code>block_{block-name}</code>, where <code>{block-name}</code> is the name of the block.
** <code>type</code> — Possible values are:
*** <code>"title"</code> — Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
*** <code>"prerendered"</code> — Your block will display the content and footer returned by the WebService to get the blocks (for example, <code>core_block_get_course_blocks</code>), so your block's method will never be called.
*** Any other value — Your block will immediately call the method specified in <code>mobile.php</code> and it will use the template to render the block.
* <code>fallback</code> (optional) — This option allows you to specify a block to use in the app instead of your block. For example, you can make the app display the "My overview" block instead of your block in the app by setting <code>'fallback' => 'myoverview'</code>. The fallback will only be used if you don't specify a <code>method</code> and the <code>type</code> is different to <code>'title'</code> or <code>'prerendered'</code>. Supported from the 3.9.0 version of the app.
==Delegates==
Delegates can be classified by type of plugin. For more info about type of plugins, please see the [[#Types_of_plugins|Types of plugins]] section.
===Templates generated and downloaded when the user opens the plugins===
====<code>CoreMainMenuDelegate</code>====
You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).
====<code>CoreMainMenuHomeDelegate</code>====
You must use this delegate when you want to add new tabs in the home page (by default the app is displaying the "Dashboard" and "Site home" tabs).
====<code>CoreCourseOptionsDelegate</code>====
You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).
====<code>CoreCourseModuleDelegate</code>====
You must use this delegate for supporting activity modules or resources.
====<code>CoreUserDelegate</code>====
You must use this delegate when you want to add additional options in the user profile page in the app.
====<code>CoreCourseFormatDelegate</code>====
You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a <code>CoreCourseFormatDelegate</code> handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format.

You can learn more about this at the [[Creating mobile course formats]] page.
====<code>CoreSettingsDelegate</code>====
You must use this delegate to add a new option in the settings page.
====<code>AddonMessageOutputDelegate</code>====
You must use this delegate to support a message output plugin.
====<code>CoreBlockDelegate</code>====
You must use this delegate to support a block. For example, blocks can be displayed in Site Home, Dashboard and the Course page.
===Templates downloaded on login and rendered using JS data===
====<code>CoreQuestionDelegate</code>====
You must use this delegate for supporting question types.

You can learn more about this at the [[Creating mobile question types]] page.
====<code>CoreQuestionBehaviourDelegate</code>====
You must use this delegate for supporting question behaviours.
====<code>CoreUserProfileFieldDelegate</code>====
You must use this delegate for supporting user profile fields.
====<code>AddonModQuizAccessRuleDelegate</code>====
You must use this delegate to support a quiz access rule.
====<code>AddonModAssignSubmissionDelegate</code> and <code>AddonModAssignFeedbackDelegate</code>====
You must use these delegates to support assign submission or feedback plugins.
====<code>AddonWorkshopAssessmentStrategyDelegate</code>====
You must use this delegate to support a workshop assessment strategy plugin.
===Pure JavaScript plugins===
These delegates require JavaScript to be supported. See [[#Initialisation|Initialisation]] for more information.
* <code>CoreContentLinksDelegate</code>
* <code>CoreCourseModulePrefetchDelegate</code>
* <code>CoreFileUploaderDelegate</code>
* <code>CorePluginFileDelegate</code>
* <code>CoreFilterDelegate</code>
==Available components and directives==
===Difference between components and directives===
A directive is usually represented as an HTML attribute, allows you to extend a piece of HTML with additional information or functionality. Example of directives are: <code>core-auto-focus</code>, <code>*ngIf</code>, and <code>ng-repeat</code>.

Components are also directives, but they are usually represented as an HTML tag and they are used to add custom elements to the app. Example of components are <code>ion-list</code>, <code>ion-item</code>, and <code>core-search-box</code>.

Components and directives are Angular concepts; you can learn more about them and the components come out of the box with Ionic in the following links:
* [https://angular.io/guide/built-in-directives Angular directives documentation]
* [https://ionicframework.com/docs/components Ionic components]
===Custom core components and directives===
These are some useful custom components and directives that are only available in the Moodle App. Please note that this isn’t the full list of custom components and directives, it’s just an extract of the most common ones.

You can find a full list of components and directives in the source code of the app, within [https://github.com/moodlehq/moodleapp/tree/master/src/core/components <code>src/core/components</code>] and [https://github.com/moodlehq/moodleapp/tree/master/src/core/directives <code>src/core/directives</code>].
====<code>core-format-text</code>====
This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies <code>core-external-content</code> and <code>core-link</code> to all the links and embedded media.

Data that can be passed to the directive:
* <code>text</code> (string) — The text to format.
* <code>siteId</code> (string) — Optional. Site ID to use. If not defined, it will use the id of the current site.
* <code>component</code> (string) — Optional. Component to use when downloading embedded files.
* <code>componentId</code> (string|number) — Optional. ID to use in conjunction with the component.
* <code>adaptImg</code> (boolean) — Optional, defaults to <code>true</code>. Whether to adapt images to screen width.
* <code>clean</code> (boolean) — Optional, defaults to <code>false</code>. Whether all HTML tags should be removed.
* <code>singleLine</code> (boolean) — Optional, defaults to <code>false</code>. Whether new lines should be removed to display all the text in single line. Only if <code>clean</code> is <code>true</code>.
* <code>maxHeight</code> (number) — Optional. Max height in pixels to render the content box. The minimum accepted value is 50. Using this parameter will force <code>display: block</code> to calculate the height better. If you want to avoid this, use <code>class="inline"</code> at the same time to use <code>display: inline-block</code>.
* <code>fullOnClick</code> (boolean) — Optional, defaults to <code>false</code>. Whether it should open a new page with the full contents on click. Only if <code>maxHeight</code> is set and the content has been collapsed.
* <code>fullTitle</code> (string) — Optional, defaults to <code>"Description"</code>. Title to use in full view.

Example usage:
<syntaxhighlight lang="html+ng2">
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</syntaxhighlight>
====<code>core-link</code>====
Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside <code>core-format-text</code>.

Data that can be passed to the directive:
* <code>capture</code> (boolean) — Optional, defaults to <code>false</code>. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* <code>inApp</code> (boolean) — Optional, defaults to <code>false</code>. Whether to open in an embedded browser within the app or in the system browser.
* <code>autoLogin</code> (string) — Optional, defaults to <code>"check"</code>. If the link should be open with auto-login. Accepts the following values:
** <code>"yes"</code> — Always auto-login.
** <code>"no"</code> — Never auto-login.
** <code>"check"</code> — Auto-login only if it points to the current site.

Example usage:
<syntaxhighlight lang="html+ng2">
<a href="<% cm.url %>" core-link>
</syntaxhighlight>
====<code>core-external-content</code>====
Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside <code>core-format-text</code>.

Data that can be passed to the directive:
* <code>siteId</code> (string) — Optional. Site ID to use. If not defined, it will use the id of the current site.
* <code>component</code> (string) — Optional. Component to use when downloading embedded files.
* <code>componentId</code> (string|number) — Optional. ID to use in conjunction with the component.

Example usage:
<syntaxhighlight lang="html+ng2">
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</syntaxhighlight>
====<code>core-user-link</code>====
Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:
* <code>userId</code> (number) — User id to open the profile.
* <code>courseId</code> (number) — Optional. Course id to show the user info related to that course.

Example usage:
<syntaxhighlight lang="html+ng2">
<a ion-item core-user-link userId="<% userid %>">
</syntaxhighlight>
====<code>core-file</code>====
Component to handle a remote file. It shows the file name, icon (depending on mime type) and a button to download or refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:
* <code>file</code> (object) — The file. Must have a <code>filename</code> property and either <code>fileurl</code> or <code>url</code>.
* <code>component</code> (string) — Optional. Component the file belongs to.
* <code>componentId</code> (string|number) — Optional. ID to use in conjunction with the component.
* <code>canDelete</code> (boolean) — Optional. Whether the file can be deleted.
* <code>alwaysDownload</code> (boolean) — Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* <code>canDownload</code> (boolean) — Optional, defaults to <code>true</code>. Whether file can be downloaded.

Example usage:
<syntaxhighlight lang="html+ng2">
<core-file
[file]="{
fileurl: '<% issue.url %>',
filename: '<% issue.name %>',
timemodified: '<% issue.timemodified %>',
filesize: '<% issue.size %>'
}"
component="mod_certificate"
componentId="<% cm.id %>">
</core-file>
</syntaxhighlight>
====<code>core-download-file</code>====
Directive to allow downloading and opening a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the <code>core-file</code> component since it also displays the state of the file.

Data that can be passed to the directive:
* <code>core-download-file</code> (object) — The file to download.
* <code>component</code> (string) — Optional. Component to link the file to.
* <code>componentId</code> (string|number) — Optional. Component ID to use in conjunction with the component.

Example usage (a button to download a file):
<syntaxhighlight lang="html+ng2">
<ion-button
[core-download-file]="{
fileurl: <% issue.url %>,
timemodified: <% issue.timemodified %>,
filesize: <% issue.size %>
}"
component="mod_certificate"
componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</ion-button>
</syntaxhighlight>
====<code>core-course-download-module-main-file</code>====
Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like <code>mod_resource</code>.

This directive must receive either a <code>module</code> or a <code>moduleId</code>. If no files are provided, it will use <code>module.contents</code>.

Data that can be passed to the directive:
* <code>module</code> (object) — Optional, required if module is not supplied. The module object.
* <code>moduleId</code> (number) — Optional, required if module is not supplied. The module ID.
* <code>courseId</code> (number) — The course ID the module belongs to.
* <code>component</code> (string) — Optional. Component to link the file to.
* <code>componentId</code> (string|number) — Optional, defaults to the same value as <code>moduleId</code>. Component ID to use in conjunction with the component.
* <code>files</code> (object[]) — Optional. List of files of the module. If not provided, uses <code>module.contents</code>.

Example usage:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" core-course-download-module-main-file moduleId="<% cmid %>"
courseId="<% certificate.course %>" component="mod_certificate"
[files]="[{
fileurl: '<% issue.fileurl %>',
filename: '<% issue.filename %>',
timemodified: '<% issue.timemodified %>',
mimetype: '<% issue.mimetype %>',
}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</syntaxhighlight>
====<code>core-navbar-buttons</code>====
Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <code><ion-buttons></code> found in the header.

You can use the <code>[hidden]</code> input to hide all the inner buttons if a certain condition is met.

Example usage:
<syntaxhighlight lang="html+ng2">
<core-navbar-buttons end>
<ion-button (click)="action()">
<ion-icon slot="icon-only" name="funnel"></ion-icon>
</ion-button>
</core-navbar-buttons>
</syntaxhighlight>
You can also use this to add options to the context menu, for example:
<syntaxhighlight lang="html+ng2">
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item
[priority]="500" content="Nice boat" (action)="boatFunction()"
iconAction="boat">
</core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</syntaxhighlight>
===Specific component and directives for plugins===
These are component and directives created specifically for supporting Moodle plugins.
====<code>core-site-plugins-new-content</code>====
Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:
* <code>component</code> (string) — The component of the new content.
* <code>method</code> (string) — The method to get the new content.
* <code>args</code> (object) — The params to get the new content.
* <code>preSets</code> (object) — Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* <code>title</code> (string) — The title to display with the new content. Only if <code>samePage</code> is <code>false</code>.
* <code>samePage</code> (boolean) — Optional, defaults to <code>false</code>. Whether to display the content in same page or open a new one.
* <code>useOtherData</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the arguments for the new <code>get_content</code> call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that doing <code>[useOtherData]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].

Let's see some examples.

A button to go to a new content page:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-new-content
title="<% certificate.name %>" component="mod_certificate"
method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</ion-button>
</syntaxhighlight>
A button to load new content in current page using <code>userid</code> from <code>otherdata</code>:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-new-content
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</ion-button>
</syntaxhighlight>
====<code>core-site-plugins-call-ws</code>====
Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see [[#core-site-plugins-call-ws-new-content|<code>core-site-plugins-call-ws-new-content</code>]].

Data that can be passed to the directive:
* <code>name</code> (string) — The name of the WS to call.
* <code>params</code> (object) — The params for the WS call.
* <code>preSets</code> (object) — Extra options for the WS call: whether to use cache or not, etc.
* <code>useOtherDataForWS</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that <code>[useOtherDataForWS]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].
* <code>confirmMessage</code> (string) — Message to confirm the action when theuser clicks the element. If not supplied, no confirmation will be requested. If supplied but empty, "Are you sure?" will be used.
* <code>showError</code> (boolean) — Optional, defaults to <code>true</code>. Whether to show an error message if the WS call fails. This field was added in 3.5.2.
* <code>successMessage</code> (string) — Message to show on success. If not supplied, no message. If supplied but empty, defaults to "Success".
* <code>goBackOnSuccess</code> (boolean) — Whether to go back if the WS call is successful.
* <code>refreshOnSuccess</code> (boolean) — Whether to refresh the current view if the WS call is successful.
* <code>onSuccess</code> (Function) — A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in 3.5.2.
* <code>onError</code> (Function) — A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in 3.5.2.
* <code>onDone</code> (Function) — A function to call when the WS call finishes (either success or fail). This field was added in 3.5.2.

Let's see some examples.

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
[preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage
refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</ion-button>
</syntaxhighlight>
A button to send some data to the server using cache without confirming, going back on success and using <code>userid</code> from <code>otherdata</code>:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</ion-button>
</syntaxhighlight>
Same as the previous example, but implementing custom JS code to run on success:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
[useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</ion-button>
</syntaxhighlight>
In the JavaScript side, you would do:
<syntaxhighlight lang="javascript">
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</syntaxhighlight>
====<code>core-site-plugins-call-ws-new-content</code>====
Directive to call a WS when the element is clicked and load a new content passing the WS result as arguments. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see [[#core-site-plugins-call-ws|<code>core-site-plugins-call-ws</code>]].

Data that can be passed to the directive:
* <code>name</code> (string) — The name of the WS to call.
* <code>params</code> (object) — The parameters for the WS call.
* <code>preSets</code> (object) — Extra options for the WS call: whether to use cache or not, etc.
* <code>useOtherDataForWS</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that <code>[useOtherDataForWS]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].
* <code>confirmMessage</code> (string) — Message to confirm the action when theuser clicks the element. If not supplied, no confirmation will be requested. If supplied but empty, "Are you sure?" will be used.
* <code>showError</code> (boolean) — Optional, defaults to <code>true</code>. Whether to show an error message if the WS call fails. This field was added in 3.5.2.
* <code>component</code> (string) — The component of the new content.
* <code>method</code> (string) — The method to get the new content.
* <code>args</code> (object) — The parameters to get the new content.
* <code>title</code> (string) — The title to display with the new content. Only if <code>samePage</code> is <code>false</code>.
* <code>samePage</code> (boolean) — Optional, defaults to <code>false</code>. Whether to display the content in the same page or open a new one.
* <code>useOtherData</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the arguments for the new <code>get_content</code> call. The format is the same as in <code>useOtherDataForWS</code>.
* <code>jsData</code> (any) — JS variables to pass to the new page so they can be used in the template or JS. If <code>true</code> is supplied instead of an object, all initial variables from current page will be copied. This field was added in 3.5.2.
* <code>newContentPreSets</code> (object) — Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in 3.6.0.
* <code>onSuccess</code> (Function) — A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in 3.5.2.
* <code>onError</code> (Function) — A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in 3.5.2.
* <code>onDone</code> (Function) — A function to call when the WS call finishes (either success or fail). This field was added in 3.5.2.

Let's see some examples.

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws-new-content
name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}"
[preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage
title="<% certificate.name %>" component="mod_certificate"
method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</ion-button>
</syntaxhighlight>
A button to get some data from the server using cache, without confirm, displaying new content in same page and using <code>userid</code> from <code>otherdata</code>:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws-new-content
name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}"
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}"
samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</ion-button>
</syntaxhighlight>

Same as the previous example, but implementing a custom JS code to run on success:
<syntaxhighlight lang="html+ng2">
<ion-button core-site-plugins-call-ws-new-content
name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}"
component="mod_certificate" method="mobile_issues_view"
[args]="{cmid: <% cmid %>, courseid: <% courseid %>}"
samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</ion-button>
</syntaxhighlight>
In the JavaScript side, you would do:
<syntaxhighlight lang="javascript">
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</syntaxhighlight>
====<code>core-site-plugins-call-ws-on-load</code>====
Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see [[#core-site-plugins-call-ws|<code>core-site-plugins-call-ws</code>]].
* <code>name</code> (string) — The name of the WS to call.
* <code>params</code> (object) — The parameters for the WS call.
* <code>preSets</code> (object) — Extra options for the WS call: whether to use cache or not, etc.
* <code>useOtherDataForWS</code> (any) — Whether to include <code>otherdata</code> (from the <code>get_content</code> WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (<code>null</code>, <code>false</code> or an empty string) all the <code>otherdata</code> will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that <code>[useOtherDataForWS]=""</code> is the same as not supplying it, so nothing will be copied. Also, objects or arrays in <code>otherdata</code> will be converted to a JSON encoded string.
* <code>form</code> (string) — ID or name to identify a form in the template. The form will be obtained from <code>document.forms</code>. If supplied and a form is found, the form data will be retrieved and sent to the new <code>get_content</code> WS call. If your form contains an <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code>, please see [[#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS]].
* <code>onSuccess</code> (Function) — A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in 3.5.2.
* <code>onError</code> (Function) — A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in 3.5.2.
* <code>onDone</code> (Function) — A function to call when the WS call finishes (either success or fail). This field was added in 3.5.2.

Example usage:
<syntaxhighlight lang="html+ng2">
<span core-site-plugins-call-ws-on-load
name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}"
[preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)">
</span>
</syntaxhighlight>
In the JavaScript side, you would do:
<syntaxhighlight lang="javascript">
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</syntaxhighlight>
==Advanced features==
===Display the plugin only if certain conditions are met===
You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the initialisation method (for more info, please see the [[#Initialisation|Initialisation]] section ahead).

All initialisation methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return the following in the initialisation method (only for Moodle site 3.8 and onwards):
<syntaxhighlight lang="php">
return ['disabled' => true];
</syntaxhighlight>
If the Moodle site is older than 3.8, then the initialisation method should return this instead:
<syntaxhighlight lang="php">
return ['javascript' => 'this.HANDLER_DISABLED'];
</syntaxhighlight>
On the other hand, you might want to display a plugin only for certain courses (<code>CoreCourseOptionsDelegate</code>) or only if the user is viewing certain users' profiles (<code>CoreUserDelegate</code>). This can be achieved with the initialisation method too.

In the initialisation method you can return a <code>restrict</code> property with two fields in it: <code>courses</code> and <code>users</code>. If you return a list of courses IDs in this property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.
===Using <code>otherdata</code>===
The values returned by the functions in <code>otherdata</code> are added to a variable so they can be used both in JavaScript and in templates. The <code>otherdata</code> returned by an initialisation call is added to a variable named <code>INIT_OTHERDATA</code>, while the <code>otherdata</code> returned by a <code>get_content</code> WS call is added to a variable named <code>CONTENT_OTHERDATA</code>.

The <code>otherdata</code> returned by an initialisation call will be passed to the JS and template of all the <code>get_content</code> calls in that handler. The <code>otherdata</code> returned by a <code>get_content</code> call will only be passed to the JS and template returned by that <code>get_content</code> call.

This means that, in your JavaScript, you can access and use the data like this:
<syntaxhighlight lang="javascript">
this.CONTENT_OTHERDATA.myVar;
</syntaxhighlight>
And in the template you could use it like this:
<syntaxhighlight lang="html+ng2">
{{ CONTENT_OTHERDATA.myVar }}
</syntaxhighlight>
<code>myVar</code> is the name we put to one of our variables, it can be any name that you want. In the example above, this is the <code>otherdata</code> returned by the PHP method:
<syntaxhighlight lang="php">
['myVar' => 'Initial value']
</syntaxhighlight>
====Example====
In our plugin, we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain Web Service. This can be done using <code>otherdata</code>.

We will return the initial value of the input in the <code>otherdata</code> of our PHP method:
<syntaxhighlight lang="php">
'otherdata' => ['myVar' => 'My initial value'],
</syntaxhighlight>
Then in the template we will use it like this:
<syntaxhighlight lang="html+ng2">
<ion-item text-wrap>
<ion-label position="stacked">{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<ion-button expand="block" color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</ion-button>
</ion-item>
</syntaxhighlight>
In the example above, we are creating an input text and we use <code>[(ngModel)]</code> to use the value in <code>myVar</code> as the initial value and to store the changes in the same <code>myVar</code> variable. This means that the initial value of the input will be "My initial value", and if the user changes the value of the input these changes will be applied to the <code>myVar</code> variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the <code>core-site-plugins-call-ws</code> directive. We use the <code>useOtherDataForWS</code> attribute to specify which variable from <code>otherdata</code> we want to send to our WebService. So if the user enters "A new value" in the input and then clicks the button, it will call the WebService <code>mod_certificate_my_webservice</code> and will send as a parameter <code>['myVar' => 'A new value']</code>.

We can also achieve the same result using the <code>params</code> attribute of the <code>core-site-plugins-call-ws</code> directive instead of using <code>useOtherDataForWS</code>:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" color="light" core-site-plugins-call-ws
name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</ion-button>
</syntaxhighlight>
The Web Service call will be exactly the same with both versions.

Notice that this example could be done without using <code>otherdata</code> too, using the <code>form</code> input of the <code>core-site-plugins-call-ws</code> directive.
===Running JS code after a content template has loaded===
When you return JavaScript code from a handler function using the <code>javascript</code> array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use <code>setTimeout</code> to call it. For example:
<syntaxhighlight lang="php">
return [
'template' => [
// ...
],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => [],
];
</syntaxhighlight>
Notice that if you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an initialisation template, so that it does not get loaded again with each page of content.
===JS functions visible in the templates===
The app provides some JavaScript functions that can be used from the templates to update, refresh or view content. These are the functions:
* <code>openContent(title: string, args: any, component?: string, method?: string)</code> — Open a new page to display some new content. You need to specify the <code>title</code> of the new page and the <code>args</code> to send to the method. If <code>component</code> and <code>method</code> aren't provided, it will use the same as in the current page.
* <code>refreshContent(showSpinner = true)</code> — Refresh the current content. By default, it will display a spinner while refreshing. If you don't want it to be displayed, you should pass <code>false</code> as a parameter.
* <code>updateContent(args: any, component?: string, method?: string)</code> — Refresh the current content using different parameters. You need to specify the <code>args</code> to send to the method. If <code>component</code> and <code>method</code> aren't provided, it will use the same as in the current page.
====Examples====
=====Group selector=====
Imagine we have an activity that uses groups and we want to let the user select which group they want to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down, we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's <code>ngModel</code>.
======Using plain HTML======
We need to add a <code>selected</code> attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:
<syntaxhighlight lang="php">
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = [
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups,
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
];
</syntaxhighlight>
In the code above, we're retrieving the groups the user can see and then we're adding a <code>selected</code> boolean to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:
<syntaxhighlight lang="html+handlebars">
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</syntaxhighlight>
The <code>ionChange</code> function will be called every time the user selects a different group with the drop down. We're using the <code>updateContent</code> function to update the current view using the new group. <code>$event</code> is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.
======Using <code>ngModel</code>======
<code>ngModel</code> is an Angular directive that allows storing the value of a certain input or select in a JavaScript variable, and also the opposite way: tell the input or select which value to set. The main problem is that we cannot initialise a JavaScript variable from the template, so we'll use <code>otherdata</code>.

In the PHP function we'll return the group that needs to be selected in the <code>otherdata</code> array:
<syntaxhighlight lang="php">
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

// ...

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'otherdata' => [
'group' => $groupid,
],
];
</syntaxhighlight>
In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the group id in the <code>otherdata</code> array. As it's explained in the [[#Using_otherdata|Using <code>otherdata</code>]] section, this <code>otherdata</code> is visible in the templates inside a variable named <code>CONTENT_OTHERDATA</code>. So in the template we'll use this variable like this:
<syntaxhighlight lang="html+handlebars">
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group"
(ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})"
interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</syntaxhighlight>
===Use the rich text editor===
The rich text editor included in the app requires a <code>FormControl</code> to work. You can use the <code>FormBuilder</code> library to create this control (or to create a whole <cide>FormGroup if you prefer).

With the following JavaScript you'll be able to create a <code>FormControl</code>:
<syntaxhighlight lang="javascript">
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</syntaxhighlight>
In the example above we're using a value returned in <code>OTHERDATA</code> as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:
<syntaxhighlight lang="html+ng2">
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer">
</core-rich-text-editor>
</ion-item>
</syntaxhighlight>
Finally, there are several ways to send the value in the rich text editor to a Web Service to save it. This is one of the simplest options:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ...
</syntaxhighlight>
As you can see, we're passing the value of the rich text editor as a parameter to our Web Service.
===Initialisation===
All handlers can specify an <code>init</code> method in the <code>mobile.php</code> file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the <code>tool_mobile_get_content</code> Web Service with the initialisation method. This WS call will only receive the default arguments.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the <code>mobile.php</code> data.

The templates returned by this method will be added to a <code>INIT_TEMPLATES</code> variable that will be passed to all the JavaScript code of that handler. This means that the JavaScript returned by the initialisation method or the main method can access any of the templates HTML like this:
<syntaxhighlight lang="javascript">
this.INIT_TEMPLATES['main'];
</syntaxhighlight>
In this case, <code>main</code> is the ID of the template we want to use.

The same happens with the <code>otherdata</code> returned by the initialisation method, it is added to an <code>INIT_OTHERDATA</code> variable.

The <code>restrict</code> field returned by this call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate <code>CoreCourseOptionsDelegate</code> and you return a list of course ids in <code>restrict.courses</code>, then your handler will only be enabled in the courses you returned. This only applies to the default handlers, if you register your own handler using the JavaScript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this initialisation JavaScript code, all the properties of that object will be passed to all the JavaScript code of that handler so you can use them when the code is run. For example, if your JavaScript code does something like this:
<syntaxhighlight lang="javascript">
var result = {
MyAddonClass: new MyAddonClass()
};

result;
</syntaxhighlight>
Then, for the rest of JavaScript code of your handler (for example, the main method) you can use this variable like this:
<syntaxhighlight lang="javascript">
this.MyAddonClass
</syntaxhighlight>
====Examples====
=====Module link handler=====
A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using an initialisation JavaScript:
<syntaxhighlight lang="javascript">
class AddonModCertificateModuleLinkHandler extends this.CoreContentLinksModuleIndexHandler {

constructor() {
super('mmaModCertificate', 'certificate');

this.name = 'AddonModCertificateLinkHandler';
}

}

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</syntaxhighlight>
=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<syntaxhighlight lang="javascript">
class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

constructor() {
super();

this.pattern = RegExp('\/mod\/foo\/specialpage.php');
}

}
</syntaxhighlight>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority; the handler with the highest priority will be used.

All default handlers have a priority of 0, so 1 or higher will override the default.
<syntaxhighlight lang="javascript">
class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

constructor() {
super();

this.priority = 1;
}

}
</syntaxhighlight>
======Multiple actions======
Once a link has been matched, the handler's <code>getActions()</code> method determines what the link should do. This method has access to the URL and its parameters.

Different actions can be returned depending on different conditions.
<syntaxhighlight lang="javascript">
class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

getActions(siteIds, url, params) {
return [
{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [
// ...
],
},
{
// ...
},
];
}

}
</syntaxhighlight>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first valid action will be used to open the link.

If your handler is matched with a link, but a condition assessed in the <code>getActions()</code> method means you want to revert to the next highest priorty handler, you can invalidate your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing <code>/mod/foo/</code>, and force those with an id parameter that's not in the <code>supportedModFoos</code> array to open in the user's browser, rather than the app.
<syntaxhighlight lang="javascript">
const that = this;
const supportedModFoos = [...];

class AddonModFooLinkHandler extends this.CoreContentLinksHandlerBase {

constructor() {
super();

this.pattern = new RegExp('\/mod\/foo\/');
this.name = 'AddonModFooLinkHandler';
this.priority = 1;
}

getActions(siteIds, url, params) {
const action = {
action() {
that.CoreUtilsProvider.openInBrowser(url);
},
};

if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}

return [action];
}

}

this.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</syntaxhighlight>
=====Module prefetch handler=====
The <code>CoreCourseModuleDelegate</code> handler allows you to define a list of offline functions to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using offline functions.

Here’s an example on how to create a prefetch handler using the initialisation JS:
<syntaxhighlight lang="javascript">
// Create a class that extends from CoreCourseActivityPrefetchHandlerBase.
class AddonModCertificateModulePrefetchHandler extends CoreCourseActivityPrefetchHandlerBase {

constructor() {
super();

this.name = 'AddonModCertificateModulePrefetchHandler';
this.modName = 'certificate';

// This must match the plugin identifier from db/mobile.php,
// otherwise the download link in the context menu will not update correctly.
this.component = 'mod_certificate';
this.updatesNames = /^configuration$|^.*files$/;
}

// Override the prefetch call.
prefetch(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
}

}

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</syntaxhighlight>
One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same <code>cmid</code>. The app will not automatically work with this situation — it will call the offline function with the standard arguments only — so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function, the rest of the code is as above) where there are multiple values of a custom <code>section</code> parameter for the mobile function <code>mobile_document_view</code>:
<syntaxhighlight lang="javascript">
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</syntaxhighlight>
=====Single activity course format=====
In the following example, the value of <code>INIT_TEMPLATES['main']</code> is:
<syntaxhighlight lang="html+ng2">
<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>
</syntaxhighlight>
This template is returned by the initialisation method. And this is the JavaScript code returned:
<syntaxhighlight lang="javascript">
var that = this;

class AddonSingleActivityFormatComponent {

constructor() {
this.data = {};
}

ngOnChanges(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
}

doRefresh(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
}

}

class AddonSingleActivityFormatHandler {

constructor() {
this.name = 'singleactivity';
}

isEnabled() {
return true;
}

canViewAllSections() {
return false;
}

getCourseTitle(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || '';
}

displayEnableDownload() {
return false;
}

displaySectionSelector() {
return false;
}

getCourseFormatComponent() {
return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES['main'], AddonSingleActivityFormatComponent);
}

}

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</syntaxhighlight>
===Using the JavaScript API===
The JavaScript API is only supported by the delegates specified in the [[#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] section. This API allows you to override any of the functions of the default handler.

The <code>method</code> specified in a handler registered in the <code>CoreUserProfileFieldDelegate</code> will be called immediately after the initialisation method, and the JavaScript returned by this method will be run. If this JavaScript code returns an object with certain functions, these functions will override the ones in the default handler.

For example, if the JavaScript returned by the method returns something like this:
<syntaxhighlight lang="javascript">
var result = {
getData: function(field, signup, registerAuth, formValues) {
// ...
}
};
result;
</syntaxhighlight>
The the <code>getData</code> function of the default handler will be overridden by the returned <code>getData</code> function.

The default handler for <code>CoreUserProfileFieldDelegate</code> only has 2 functions: <code>getComponent</code> and <code>getData</code>. In addition, the JavaScript code can return an extra function named <code>componentInit</code> that will be executed when the component returned by <code>getComponent</code> is initialised.

Here’s an example on how to support the text user profile field using this API:
<syntaxhighlight lang="javascript">
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = 'profile_field_' + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || '';
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? 'password' : 'text';

var formData = {
value: this.field.defaultdata,
disabled: this.disabled,
};

this.form.addControl(this.field.modelName,
that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = 'profile_field_' + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name]),
};
}
};

result;
</syntaxhighlight>
===Translate dynamic strings===
If you wish to have an element that displays a localised string based on value from your template you can doing something like:
<syntaxhighlight lang="html+handlebars">
<ion-card>
<ion-card-content>
{{ 'plugin.mod_myactivity.<% status %>' | translate }}
</ion-card-content>
</ion-card>
</syntaxhighlight>
This could save you from having to write something like when only one value should be displayed:
<syntaxhighlight lang="html+handlebars">
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</syntaxhighlight>
===Using strings with dates===
If you have a string that you wish to pass a formatted date, for example in the Moodle language file you have:
<syntaxhighlight lang="php">
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</syntaxhighlight>
You can localise the string correctly in your template using something like the following:
<syntaxhighlight lang="html+handlebars">
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</syntaxhighlight>
A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, whereas Unix timestamps are in seconds.
===Support push notification clicks===
If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a <code>contexturl</code> in your notification. When the notification is clicked, the app will try to open the <code>contexturl</code>.

Please notice that the <code>contexturl</code> will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a <code>customdata</code> array that contains an <code>appurl</code> property:
<syntaxhighlight lang="php">
$notification->customdata = [
'appurl' => $myurl->out(),
];
</syntaxhighlight>
In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[#Advanced_link_handler|creating an advanced link handler]], but you'll have to use <code>CorePushNotificationsDelegate</code> and your handler will have to implement the properties and functions defined in the [https://github.com/moodlehq/moodleapp/blob/master/src/core/features/pushnotifications/services/push-delegate.ts#L27 CorePushNotificationsClickHandler] interface.
===Implement a module similar to mod_label===
In Moodle 3.8 or higher, if your plugin doesn't support <code>FEATURE_NO_VIEW_LINK</code> and you don't specify a <code>coursepagemethod</code> then the module will only display the module description in the course page and it won't be clickable in the app, just like <code>mod_label</code>. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in <code>displaydata</code>).

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the <code>coursepagemethod</code> property in <code>mobile.php</code>. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only plain HTML.

If you don't want your module to be clickable then you just need to remove <code>method</code> from <code>mobile.php</code>. With these 2 changes you can have a module that behaves like <code>mod_label</code> in the app.
===Use Ionic navigation lifecycle functions===
Ionic let pages define some functions that will be called when certain navigation lifecycle events happen. For more info about these functions, see [https://ionicframework.com/docs/api/router-outlet Ionic's documentation].

You can define these functions in your plugin javascript:
<syntaxhighlight lang="javascript">
this.ionViewWillLeave = function() {
// ...
};</syntaxhighlight>
In addition to that, you can also implement <code>canLeave</code> to use Angular route guards:
<syntaxhighlight lang="javascript">
this.canLeave = function() {
// ...
};</syntaxhighlight>
So for example you can make your plugin ask for confirmation if the user tries to leave the page when he has some unsaved data.
===Module plugins: dynamically determine if a feature is supported===
In Moodle you can specify if your plugin supports a certain feature, like <code>FEATURE_NO_VIEW_LINK</code>. If your plugin will always support or not a certain feature, then you can use the <code>supportedfeatures</code> property in <code>mobile.php</code> to specify it ([[#Options_only_for_CoreCourseModuleDelegate|see more documentation about this]]). But if you need to calculate it dynamically then you will have to create a function to calculate it.

This can be achieved using the initialisation method (for more info, please see the [[#Initialisation|Initialisation]] section above). The JavaScript returned by your initialisation method will need to define a function named <code>supportsFeature</code> that will receive the name of the feature:
<syntaxhighlight lang="javascript">
var result = {
supportsFeature: function(featureName) {
// ...
}
};
result;
</syntaxhighlight>
Currently the app only uses <code>FEATURE_MOD_ARCHETYPE</code> and <code>FEATURE_NO_VIEW_LINK</code>.
== Testing ==
You can also write automated tests for your plugin using Behat, you can read more about it on the [[Acceptance testing for the Moodle App]] page.
== Upgrading plugins from an older version ==
If you added mobile support to your plugin for the Ionic 3 version of the app (previous to the 3.9.5 release), you will probably need to make some changes to make it compatible with Ionic 5.

Learn more at the [[Moodle App Plugins Upgrade Guide]].
==Troubleshooting==
=== Invalid response received ===
You might receive this error when using the <code>core-site-plugins-call-ws</code> directive or similar. By default, the app expects all Web Service calls to return an object, if your Web Service returns another type (string, boolean, etc.) then you need to specify it using the <code>preSets</code> attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:
<syntaxhighlight lang="html+ng2">
[preSets]="{typeExpected: 'boolean'}"
</syntaxhighlight>
In a similar way, if your Web Service returns <code>null</code> you need to tell the app not to expect any result using <code>preSets</code>:
<syntaxhighlight lang="html+ng2">
[preSets]="{responseExpected: false}"
</syntaxhighlight>
=== Values of <code>ion-radio</code>, <code>ion-checkbox</code> or <code>ion-select</code> aren't sent to my WS ===
Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, <code>ion-radio</code>, <code>ion-checkbox</code> and <code>ion-select</code> don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the Web Service.

There are 2 workarounds to fix this problem.
==== Sending the data manually ====
The first solution is to send the missing params manually using the <code>params</code> property. We will use <code>ngModel</code> to store the input value in a variable, and this variable will be passed to the parameters. Please notice that <code>ngModel</code> requires the element to have a name, so if you add <code>ngModel</code> to a certain element you need to add a name too.

For example, if you have a template like this:
<syntaxhighlight lang="html+ng2">
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<ion-button expand="block" type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</ion-button>
</syntaxhighlight>
Then you should modify it like this:
<syntaxhighlight lang="html+ng2">
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<ion-button expand="block" type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</ion-button>
</syntaxhighlight>
Basically, you need to add <code>ngModel</code> to the affected element (in this case, the <code>radio-group</code>). You can put whatever name you want as the value, we used "responses". With this, every time the user selects a radio button the value will be stored in a variable called "responses". Then, in the button we are passing this variable to the parameters of the Web Service.

Please notice that the <code>form</code> attribute has priority over <code>params</code>, so if you have an input with <code>name="responses"</code> it will override what you're manually passing to <code>params</code>.
==== Using a hidden input ====
Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use <code>ngModel</code> to synchronise your radio/checkbox/select with the new hidden input. Please notice that <code>ngModel</code> requires the element to have a name, so if you add <code>ngModel</code> to a certain element you need to add a name too.

For example, if you have a radio button like this:
<syntaxhighlight lang="html+ng2">
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</syntaxhighlight>
Then you should modify it like this:
<syntaxhighlight lang="html+ng2">
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</syntaxhighlight>
In the example above, we're using a variable called "responses" to synchronise the data between the <code>radio-group</code> and the hidden input. You can use whatever name you want.
=== I can't return an object or array in <code>otherdata</code> ===
If you try to return an object or an array in any field inside <code>otherdata</code>, the Web Service call will fail with the following error:
<syntaxhighlight lang="text">
Scalar type expected, array or object received
</syntaxhighlight>
Each field in <code>otherdata</code> must be a string, number or boolean; it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:
<syntaxhighlight lang="php">
'otherdata' => ['data' => json_encode($data)],
</syntaxhighlight>
The app will automatically parse this JSON and convert it back into an array or object.
==Examples==
===Accepting dynamic names in a Web Service===
We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new Web Service that we have created.

The first issue we find is that the Web Service needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the <code>_parameters()</code> function of our new Web Service, we will add this parameter:
<syntaxhighlight lang="php">
'data' => new external_multiple_structure(
new external_single_structure(
[
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
]
),
'The data to be saved', VALUE_DEFAULT, []
)
</syntaxhighlight>
Now we need to adapt our form to send the data as the Web Service requires it. In our template, we have a button with the <code>core-site-plugins-call-ws</code> directive that will send the form data to our Web Service. To make this work we will have to pass the parameters manually, without using the <code>form</code> attribute, because we need to format the data before it is sent.

Since we will send the parameters manually and we want it all to be sent in the same array, we will use <code>ngModel</code> to store the input data into a variable that we'll call <code>data</code>, but you can use the name you want. This variable will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:
<syntaxhighlight lang="javascript">
{a1: 'My answer'}
</syntaxhighlight>
So we need to add <code>ngModel</code> to all the inputs whose values need to be sent to the <code>data</code> WS param. Please notice that <code>ngModel</code> requires the element to have a name, so if you add <code>ngModel</code> to a certain element you need to add a name too. For example:
<syntaxhighlight lang="html+ng2">
<ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']">
</syntaxhighlight>
As you can see, we're using <code>CONTENT_OTHERDATA</code> to store the data. We do it like this because we'll use <code>otherdata</code> to initialise the form, setting the values the user has already stored. If you don't need to initialise the form, then you can use the <code>dataObject</code> variable, an empty object that the mobile app creates for you:
<syntaxhighlight lang="html+ng2">
[(ngModel)]="dataObject['<% name %>']"
</syntaxhighlight>
The app has a function that allows you to convert this data object into an array like the one the WS expects: <code>objectToArrayOfObjects</code>. So in our button we'll use this function to format the data before it's sent:
<syntaxhighlight lang="html+ng2">
<ion-button expand="block" type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</syntaxhighlight>
As you can see in the example above, we're specifying that the keys of the <code>data</code> object need to be stored in a property called "name", and the values need to be stored in a property called "value". If your Web Service expects different names you need to change the parameters of the <code>objectToArrayOfObjects</code> function.

If you open your plugin now in the app it will display an error in the JavaScript console. The reason is that the <code>data</code> variable doesn't exist inside <code>CONTENT_OTHERDATA</code>. As it is explained in previous sections, <code>CONTENT_OTHERDATA</code> holds the data that you return in <code>otherdata</code> for your method. We'll use <code>otherdata</code> to initialise the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialise the <code>data</code> object as an empty object. Please remember that we cannot return arrays or objects in <code>otherdata</code>, so we'll return a JSON string.
<syntaxhighlight lang="php">
'otherdata' => ['data' => '{}'],
</syntaxhighlight>
With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:
<syntaxhighlight lang="php">
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: ['a1' => 'My value'].

// ...

'otherdata' => ['data' => json_encode($userdata)],
</syntaxhighlight>
Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our Web Service in array format.
==Moodle plugins with mobile support==
* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].
See the complete list in [https://moodle.org/plugins/browse.php?list=award&id=6 the plugins database] (it may contain some outdated plugins).
=== Mobile app support award ===
If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email at [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory.
[[Category:Mobile]]
[[Category:Moodle App Ionic 5]]

Moodle App Development Guide

2022-03-15T08:55:05Z

Dpalou: /* Acceptance */

{{Moodle App (Ionic 5)}}
This document contains information that developers should know before starting to code on the Mobile App. If you are only interested in developing a site plugin, you should read [[Mobile support for plugins|the Moodle App Plugins Development Guide]] instead.

Please notice that this documentation is useful to develop code that will be integrated in the standard app or in a custom app. Developers that want to add mobile support to their Moodle plugins don’t need to follow this.

Before embarking on Moodle-specific documentation, we recommend that you are at least familiar with [https://angular.io/ Angular] and [https://ionicframework.com/ Ionic Framework], the core technologies used in the application. We’ll reference any relevant concepts, but having a basic understanding will take you a long way in understanding the Moodle App.
== Setting up your development environment ==
In order to get started, you’ll need to prepare your development environment. We recommend that you do it before proceeding with the guide, that way you can tinker with the codebase to solidify your understanding.

You can obtain a copy of the source code by cloning the public repository. If you want to work on a specific version of the app, you can check the tag with the version number you need; for example <code>v3.9.5</code>. If you want to work on the latest development version, you should check out the <code>integration</code> branch:
<syntaxhighlight lang="bash">
git clone git@github.com:moodlehq/moodleapp.git
cd moodleapp
git checkout integration # or `git checkout v3.9.5`
</syntaxhighlight>
The only things you need to install before running the app are NodeJS and npm. Make sure that you are using the correct versions of each environment (looking at the <code>engines</code> entry in <code>package.json</code>). We recommend using a version manager like [https://github.com/nvm-sh/nvm nvm] to make this easier, you can prepare the correct environment running <code>nvm install</code> in the project root. Remember to run this every time you work with the app, or if you’re not working on any other node projects in your computer you can run <code>nvm alias default `node -v`</code> to make it the default.

Once you have the correct environment set up, you can run the application with the following two commands:
<syntaxhighlight lang="bash">
npm install
npm start
</syntaxhighlight>
This will launch the application in a browser, but keep in mind that it only works with chromium-based browsers. You can read more about that in the [[Using the Moodle App in a browser]] page.

Other than this, there are different things you’ll need to do depending on what you are trying to achieve. We’ll go over some of them briefly, but if you want to learn more about this or something isn’t working as you expect, make sure to check out the full guide on [[Setting up your development environment for Moodle Mobile 2|Setting up your development environment]].
=== Editing code ===
You can use your favorite editor to work on the application.

We recommend using [https://code.visualstudio.com/ VSCode] as it is the one used by the core team and the repository is configured with some specific settings for the Moodle App.

The code follows the [[Moodle App Coding Style]], and many of the style rules are enforced with [https://eslint.org/ ESLint]. If you are using VSCode, you can automatically lint your files using the [https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint ESLint extension].
=== Debugging ===
While working on the app, you’ll want to debug what’s going on under the hood. The application uses a logging mechanism to inform of what’s happening, so if you open the console during development you will see a bunch of messages that you may find useful.

If you are working on something related with the user interface, it is useful to inspect the state of the Angular components in the page. You can do that using the [https://github.com/anton-lunev/angular-state-inspector Angular State Inspection browser extension].

If you are working on something that is pure logic (although it can involve components), you may want to give [[#Unit|unit testing]] a try. If you are [https://code.visualstudio.com/Docs/editor/debugging using VSCode to run the tests], you can use breakpoints right on your editor. If you are struggling to reproduce an issue in tests, you can also use breakpoints in the browser [https://developer.chrome.com/docs/devtools/javascript/ using the Sources Panel].

If you need to debug how the application is interacting with a Moodle site, you’ll need to take a look at the network requests. Most of the time [https://developer.chrome.com/docs/devtools/network/ using the Network Panel] should suffice, but if that isn’t working take a look at the [[Debugging network requests in the Moodle App]] page.
=== Working with a Moodle site ===
When you are using the app, you’ll need to connect with a Moodle site. You may already have your own site, but using a real site may not be the best choice for development.

If you’re working on something that doesn’t need anything specific from your site, you can use a test site like [https://school.moodledemo.net school.moodledemo.net]. This is a site that will reset all the data every hour, so you don’t have to worry about making any persistent change by mistake. You can also use a shortcut to log in as a student or teacher using <code>student</code> or <code>teacher</code> instead of a url. However, keep in mind that this site is also used by others who are new to Moodle, so be sensible and don’t abuse it.

If you need to configure something from the site, your best option is to run a Moodle site on your computer. Setting that up is outside the scope of this document, but we recommend using [https://github.com/moodlehq/moodle-docker moodle-docker] because it comes with everything you need (and it also supports running the app!). If you need anything specific from a course, you can always replicate it on your local site using the [https://docs.moodle.org/311/en/Backup backup and restore functionality]. You can create a backup from your production site, and restore it in your local site.
=== Working on native functionality ===
Most of the time, we recommend that you develop using a browser because it’s faster and easier to work with. However, sometimes you may need native functionality that is only available on a mobile device.

You can learn how to set up your environment by reading Ionic’s documentation for [https://ionicframework.com/docs/developing/android Android] and [https://ionicframework.com/docs/developing/ios iOS]. The Moodle App also comes with some npm scripts used for native development. You can build and launch the app by calling <code>npm run dev:android</code> and <code>npm run dev:ios</code>.
== Folders structure ==
In this section, we’ll see how files and folders are organised within the <code>src/</code> folder.
=== index.html ===
This html file contains the shell where the application will be rendered. Before the app is ready, even before JavaScript is loaded, this is what the application will look like. In a mobile device, users will never see this because it is hidden by the splash screen until the application is ready. That’s why there isn’t any markup other than the root component that will be rendered by Angular.

You won’t see any script files referenced here because those are injected later in the compilation process. You can see the actual file in the <code>www/</code> folder after running the build script.
=== main.ts ===
This file is the main entry point of the application, the first code that runs when the application is launched. The application is bootstrapped by Angular using our root application module.

You can learn more about this in the [[#Application_lifecycle|Application Lifecycle]] section.
=== polyfills.ts ===
This file adds [https://en.wikipedia.org/wiki/Polyfill_(programming) polyfills] for missing functionality in the platform.
=== app/ ===
This folder contains the root component and the root module of the application.

You will notice that the app.module.ts file is quite small. This is because it only includes Angular and Ionic boilerplate, leaving the heavy lifting to the code within [[#core.2F|core/]] and [[#addons.2F|addons/]].
=== core/ ===
This folder contains the basic functionality of the application, and exposes pluginable interfaces for other parts to hook into. Anything defined here can be imported anywhere since it's critical for the app and it is available everywhere (in contrast to code within [[#addons.2F|addons/]]). In order to identify code from this folder, all classes start with the <code>Core</code> prefix.

The <code>core.module.ts</code> file defines a module that imports all the core providers and modules. It encapsulates the initialisation of the application core.

The <code>shared.module.ts</code> file defines a [https://angular.io/guide/module-types#shared-ngmodules Shared Module] that exposes core declarables (components, directives and pipes). When other modules use any of these, it’s preferable to import this module instead of individual declarable modules separately.

There is also a <code>constants.ts</code> file with global read-only values.
==== core/initializers/ ====
This folder contains a collection of scripts that are run within the [https://angular.io/api/core/APP_INITIALIZER Angular initialisation process].

These files are automatically loaded using webpack, so it isn’t necessary to import them anywhere. You can see how they are loaded in <code>src/core/initializers/index.ts</code>.

Keep in mind that any code placed here will delay the [[#Application_lifecycle|application startup]], so it’s critical that only the essential processes are included here. If something can be initialised lazily, it should.
==== core/services/ ====
This folder contains [https://angular.io/guide/architecture-services Angular services] available anywhere in the application.

Most of them are [https://angular.io/guide/singleton-services Singleton Services], and they can be accessed statically using their corresponding [[#Service_singleton|Service Singleton]].

Given that services are created on demand, none of them is guaranteed to be initialised when the application is ready. So anything that’s essential for the application to run should be placed in an [[#core.2Finitializers.2F|initializer]] instead. In case that the initialisation relies on a service, it can be accessed using its Service Singleton. One good example of this is the database initialisation, which is placed on an initializer but calls each service’s <code>initializeDatabase</code> method.

And of course, service dependencies can be declared in the constructor to use Angular’s built-in dependency management.
==== core/components/ ====
This folder contains [https://angular.io/guide/architecture-components Angular components] available anywhere in the application (but remember that they should be imported explicitly using <code>CoreSharedModule</code>). They are exposed to the shared module using their own module: <code>CoreComponentsModule</code>.

This folder also contains an <code>animations.ts</code> file with reusable [https://angular.io/guide/animations Angular animations].

All components must be declared with tag selectors starting with their module namespace (''core-'' in this case), and defined within a folder with their selector (without the namespace prefix). These component folders can contain the following files:
* <code>{component-name}.ts</code> — Component class.
* <code>{namespace}-{component-name}.html</code> — Component template.
* <code>{component-name}.scss</code> — Component-scoped styles.

Additionally, auxiliary components that are only used locally can be defined in the same folder, starting with the name of their parent component. For example, looking at the <code>core-recaptcha</code> component we can find the following files:
* <code>recaptcha.ts</code> — Recaptcha component class.
* <code>core-recaptcha.html</code> — Recaptcha component template.
* <code>recaptcha-modal.ts</code> — Auxiliary modal component class.
* <code>core-recaptcha-modal.html</code> — Auxiliary modal component template.
==== core/directives/ and core/pipes/ ====
These folders contain [https://angular.io/guide/architecture-components#directives Angular directives] and [https://angular.io/guide/architecture-components#pipes Angular pipes] available anywhere in the application (but remember that they should be imported explicitly using <code>CoreSharedModule</code>).

They are exposed to the shared module using their own modules: <code>CoreDirectivesModule</code> and <code>CorePipesModule</code> respectively.
==== core/guards/ ====
This folder contains [https://angular.io/guide/router#preventing-unauthorized-access route guards] used to control access to restricted routes.

Given that we are working with a mobile application, and not deploying to the web, users won’t be able to access urls manually. But it is still important to have proper guards to prevent potential bugs and vulnerabilities.
==== core/classes/ ====
This folder contains classes that don’t fit into any other part of the application. We must be careful not to bloat this folder and turn it into a mess. There can be subfolders to group files with related functionality.

Think twice before adding anything here.
==== core/utils/ ====
Same as [[#core.2Fclasses.2F|core/classes/]], but containing functional utilities instead of classes.
==== core/singletons/ ====
This folder contains some core [[#Singletons|Singletons]] and the logic to make Service Singletons.

Other than Pure Singletons, there are also some third-party services exposed through Service Singletons. However, service Singletons for application services should be declared in the same file where the service is defined.
==== core/features/ ====
This folder contains [https://angular.io/guide/module-types#domain-ngmodules Domain Modules] for core features. Each of those modules encapsulates the functionality for a given area. Even though they can rely on each other (because anything within core is globally accessible), it should be avoided to reduce coupling.

The <code>features.module.ts</code> file defines a module that imports all feature modules.

Each feature module will be different, some may only provide services while others define routing endpoints (or both). In any case, each feature is encapsulated into its own folder.

When a module needs to export something, it has a file in its root folder named <code>{feature-name}.module.ts</code> defining the main feature module.

If a module uses [https://angular.io/guide/lazy-loading-ngmodules lazy loading], that will be declared within a different module defined in <code>{feature-name}-lazy.module.ts</code>, and the lazy routes are exposed through the main feature module. In this way, the knowledge of which routes are loaded lazily is encapsulated within each feature folder.

Sometimes, it’s possible that a feature allows nested routes to be defined from other modules. For example, the ''mainmenu'' feature allows other modules to add extra tabs. In those situations, these features will also have a <code>{feature-name}-routing.module.ts</code> file.

You can learn more about the contents and motivation of these files in the [[#Routing|Routing]] section.

In addition to these files, feature folders may contain the following:
* <code>{feature-name}.scss</code> — Reusable styles for components defined in this module.
* <code>classes/</code> — Same as [[#core.2Fclasses.2F|core/classes/]].
* <code>utils/</code> — Same as [[#core.2Futils.2F|core/utils/]].
* <code>components/</code> — Same as [[#core.2Fcomponents.2F|core/components/]] (with the ''core-{feature-name}-'' namespace).
* <code>directives/</code> and <code>pipes/</code> — Same as [[#core.2Fdirectives.2F|core/directives/]] and [[#core.2Fpipes.2F|core/pipes/]].
* <code>lang/</code> — Same as [[#core.2Flang.2F|core/lang/]].
* <code>services/</code> — Same as [[#core.2Fservices.2F|core/services/]].
* <code>pages/</code> — Page folders have the same structure as [[#core.2Fcomponents.2F|core/components/]], but in addition they often declare modules as well to allow lazy-loading the page. In some cases, they can even have their own routing modules. For example, look at <code>core/features/mainmenu/pages/home/home-routing.module.ts</code>.

In order to distinguish code from each feature, classes will be prefixed with the feature name. For example, the home page component declared in <code>core/features/mainmenu/pages/home/home.ts</code> is called <code>CoreMainMenuHomePage</code>.
=== addons/ ===
This folder contains [https://angular.io/guide/module-types#domain-ngmodules Domain Modules] for additional features. Its structure is similar to [[#core.2Ffeatures.2F|core/features/]], but the namespace is ''addon-{addon-name}-'' and addon modules are decoupled from core and each other. This means that any code within core shouldn’t import anything from addons, and addons shouldn’t import anything from each other.

This level of decoupling can be achieved using the [https://en.wikipedia.org/wiki/Dependency_inversion_principle Dependency Inversion Principle], which in this case is easier to apply using [https://angular.io/guide/dependency-injection Angular’s Dependency Injection framework]. However, this theoretical nirvana has not been achieved in the current status of the codebase. And it’s arguable whether it is desirable, given the cost of adhering strictly to this pattern.

For example, calendar blocks defined in the ''block'' addon import a provider declared in the ''calendar'' addon. This violates the dependency inversion principle, but it’s a sensible decision to avoid complicating the code in excess.

The end goal is to make each addon as independent as possible, keeping practicality and simplicity in mind.

In order to distinguish code from each addon, classes will be prefixed with ''Addon'' + the addon name. For example, the private files page component declared in <code>core/addons/privatefiles/pages/index/index.ts</code> is called <code>AddonPrivateFilesIndexPage</code>.
=== types/ ===
This folder contains global [https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html TypeScript declaration files].
=== testing/ ===
This folder contains supporting code for writing tests, but does not contain any tests. To learn where tests are located, read the [[#Test_files|Test files]] section.
=== theme/ ===
This folder contains general app style sheets. theme.scss is the one that will be included in the html, the rest will be imported by theme or children of this.
* <code>theme.scss</code> — This is the main file and contains imports to the rest of the files and 3rd party styles.
* <code>theme.light.scss</code> — Includes the desired variables for the light color scheme.
* <code>theme.dark.scss</code> — Includes the desired variables for the dark color scheme.
* <code>theme.custom.scss</code> — Includes custom styles.
* <code>theme.base.scss</code> — Contains global styles, css rules that will apply across the app.
* <code>globals.scss</code> — Introduces scss functionality on the the styles and contains imports to:
** <code>globals.custom.scss</code> — Global custom scss variables.
** <code>globals.variables.scss</code> — Global scss variables.
** <code>globals.mixins.scss</code> — App customised mixins.
** <code>globals.mixins.ionic.scss</code> — Imported mixins from ionic.
* <code>format-text.scss</code> — Contains format-text tag styles.
=== assets/ ===
This folder contains source files that are not considered app code. This includes things like fonts, images, and json files; but also external libraries that couldn’t be installed using npm (for example, h5p and mathjax).

An exception to this rule is <code>js/iframe-treat-link.js</code>, which is a file that can be considered app code but it is injected directly into iframes without a compilation step.
=== File names ===
As a rule of thumb, TypeScript files should be named after the class or interface they export. Given that [https://stackoverflow.com/questions/45962317/why-isnt-export-default-recommended-in-angular it’s discouraged to use default exports in Angular applications], it is not obvious what that is for each file. But in most cases it should be fairly easy to see. In situations where there isn’t a single relevant export, like a file exporting multiple functions, you should use a name that properly reflects the nature of this grouping.

File names should use [https://en.wikipedia.org/wiki/Letter_case#Kebab_case kebab case] and not include namespaces nor type suffixes. For example, if there is a service declared within <code>core/services/</code> called <code>CoreFoobarService</code>, its file name should be <code>foobar.ts</code>, not <code>core-foobar-service.ts</code>.

If a folder contains more than one type of TypeScript file, the type of file should be added as a suffix with a dot. For example, the <code>app/</code> folder contains multiple types of classes and that’s why the file declaring the root component is named <code>app.component.ts</code>. Most components elsewhere don’t have the ''.component'' suffix. The exception to this rule are module and test files, which must always use the ''.module'' and ''.test'' suffix respectively.
=== Language files ===
All feature and addon folders can contain a lang.json file, as well as the <code>core/</code> folder. The JSON file contains all translatable string keys with the current english text. During compilation, those files will be merged into one single file on <code>assets/lang/en.json</code> that will contain the cooked string keys (every key of those files will be prepended with the module prefix).

An automatic process will create the rest of the language files on the <code>assets/lang/</code> folder based on the Moodle translation platform: [https://lang.moodle.org/ AMOS].

In order to match existing Moodle language strings with the app strings the app contains a file on the scripts folder called <code>langindex.json</code>. This file contains an indexed array with the cooked string keys of the app, the value of every item is the module (file name) where to find the string in AMOS. If the value contains a slash ‘/’ the text before the slash will correspond to the module (file name) and the text after will correspond to the string key on that file. If it does not contain a slash, the string key will be the last part of the cooked string key (splitting using dots .).
=== Test files ===
Tests are found anywhere inside the <code>src/</code> folder, and they will be run as long as they end with ''.test.ts''. As a general rule, they are placed in a folder next to the module responsible for the code being tested. And they mirror the folder structure.

Here are some examples:
* The utils text service declared in <code>core/services/utils/text.ts</code> is tested in <code>core/services/tests/utils/text.test.ts</code>.
* The init login page declared in <code>core/features/login/pages/init/init.ts</code> is tested in <code>core/features/login/tests/pages/init.test.ts</code>. The test file can be directly under <code>pages/</code> (instead of <code>pages/init/</code>) because the page component is the only file that will be tested for this folder. So it would be unnecessary to have a folder with a single file.
* The root app component declared in <code>app/app.component.ts</code> is tested in <code>app/app.component.test.ts</code>. The test file can live alongside the component because this module doesn’t have any nested folders.

In addition to unit test files, there is also a folder at <code>testing/</code> with setup and file utilities shared among all tests.

Learn more about unit tests in the [[#Testing|Testing]] section.
== Routing ==
All core features and addons can define their own routes, and we can do that in their main module. However, those are loaded when the application starts up, and that won’t be desirable in most cases. In those situations, we can use [https://angular.io/guide/lazy-loading-ngmodules lazy loading] to defer it until necessary. To encapsulate lazy functionality, we can define a [https://angular.io/guide/module-types#routed Routed Module] named <code>{feature-name}LazyModule</code>. For example, the ''login'' core feature defines both a <code>CoreLoginModule</code> and a <code>CoreLoginLazyModule</code>.

With the [[#Folders_structure|folders structure]] we’re using, it is often the case where different core features or addons need to define routes depending on each other. For example, the ''mainmenu'' feature defines the layout and routes for the tabs that are always present at the bottom of the UI. But the home tab is defined in the ''home'' feature. In this scenario, it would be possible to just import the pages from the ''home'' module within the ''mainmenu'', since both are core features and are allowed to know each other. But that approach can become messy, and what happens if an addon also needs to define a tab (like ''privatefiles'')?

As described in the [[#addons.2F|addons/ folder documentation]], the answer to this situation is using the dependency inversion pattern. Instead of the ''mainmenu'' depending on anything rendering a tab (''home'', ''privatefiles'', etc.), we can make those depend on the ''mainmenu'' instead. And we can do that using Angular’s container.

In order to allow injecting routes from other modules, we create a separated [https://angular.io/guide/module-types#routing-ngmodules Routing Module]. This is the only situation where we’ll have a dedicated module for routing, in order to reduce the amount of module files in a feature root folder. Any routes that are not injected can be defined directly on their main or lazy module.

It is often the case that modules using injected routes have a [https://angular.io/api/router/RouterOutlet RouterOutlet]. For that reason, injected routes can be defined either as children or siblings of the main route. The difference between those is that a child will be rendered within the outlet, whilst a sibling will replace the entire page. In order to make this distinction, routing modules accept either an array of routes to use as siblings or an object indicating both types of routes. You can see an example of this in the <code>core/features/courses/courses.module.ts</code> file where some ''courses'' routes are injected both as siblings and children into the home routing module.

This architecture is not limited to feature or addon modules though, page modules can also define routing modules to allow injecting routes. One example is the <code>core/features/mainmenu/pages/home/home-routing.module.ts</code> file. Notice how the accompanying module does not use the ''-lazy'' name prefix, that is because page modules are loaded by their respective feature module and they are always lazy, so it isn’t necessary to make that distinction (if a page is not lazy-loaded it doesn’t have a dedicated module).
=== Navigating between routes ===
In order to navigate between routes, you should use the <code>CoreNavigator</code> service. It works using Angular’s router under the hood, and it takes care of all the routing specific to our application.

Most of the time, you’ll probably want to use the <code>navigateToSitePath</code> method, because it will take into account the current main menu tab and navigate accordingly. If the call needs to navigate to another site, it’ll also take care of all the login workflow.

If you are navigating to a specific route that is not affected by the current site nor the main menu tab, you can use the navigate method directly. This method can also be useful if you want to navigate relative to the current route, for example doing:
<syntaxhighlight lang="javascript">
CoreNavigator.navigate('../');
</syntaxhighlight>
Other than navigation, this service also contains some helpers that are not available in Angular out of the box. For example, the <code>getRouteParam</code> will get values from multiple sources such as query parameters or route parameters, and it also supports reading non-primitive values.

Make sure to [https://github.com/moodlehq/moodleapp/blob/integration/src/core/services/navigator.ts check out the full api] to learn more about the <code>CoreNavigator</code> service.
== Singletons ==
The application relies heavily on the [https://en.wikipedia.org/wiki/Singleton_pattern Singleton design pattern], and there are two types of singletons used throughout the application: Pure singletons and Service singletons.
=== Pure Singletons ===
Pure singletons, or just “singletons”, are plain Typescript classes whose functionality does not depend on the lifecycle of the application. These normally contain helper or utility methods that enhance existing apis or encapsulate reusable functionality.

Their implementations usually consist of a collection of static methods (so technically they are not singletons, but in practice this is easier to work with).
<syntaxhighlight lang="typescript">
export class CoreArray {

static contains<T>(items: T[], item: T): boolean {
return items.indexOf(item) !== -1;
}

}
</syntaxhighlight>
=== Service Singletons ===
Service singletons are instances resolved from the [https://angular.io/guide/hierarchical-dependency-injection root application injector]. In contrast with pure singletons, these are defined as Angular services. In particular, these should be [https://angular.io/guide/singleton-services singleton services].

The motivation behind using this pattern to access service instances is improving the development experience (easier auto-imports) and delaying the instantiation of services until they are really needed.

For example, service A may rely on service B in one method. Using Angular’s dependency management you would declare service B in the constructor of service A. In this situation, service B would be instantiated whenever service A is instantiated, regardless of the method that uses it being called or not. Given the size of the codebase, this can have a cascading effect detrimental to the performance of the application. With the Service Singleton pattern, service B would only be instantiated when the method that uses it in service A is called.

To adopt this pattern, the only additional step in the service definition is to use the <code>makeSingleton</code> method (make sure to declare it as provided in root):
<syntaxhighlight lang="typescript">
@Injectable({ providedIn: 'root' })
export class CoreUserService {

// ...

}

export const CoreUser = makeSingleton(CoreUserService);
</syntaxhighlight>
This method will create a proxy that will relay all the method calls to the service singleton instance. This proxy can be used like you would use an injected instance of the service. When any method is called, the underlying service will be initialised lazily. If you need to access the actual instance, you can do it via the <code>instance</code> property.

Since they are normal Angular services under the hood, they can be overridden in other modules. But keep in mind that because they are singletons, they will be replaced everywhere and not just in the module where they are being defined.

Here’s one example of this overriding a core Angular service:
<syntaxhighlight lang="typescript">
export class MyHttpClient extends HttpClient {}

export const Http = makeSingleton(HttpClient);

@NgModule({
providers: [
{ provide: HttpClient, useClass: MyHttpClient },
],
})
export class MyModule {}
</syntaxhighlight>
This pattern can be used mostly everywhere, because the underlying system is initialised before the app initialisation begins.

The exception to this rule is within service constructors, given that we don’t have absolute control over when Angular will create service instances. For this same reason, code intended to run on application startup must be placed on an [[#core.2Finitializers.2F|initializer]]. And anything else within a service should be initialised lazily, instead of using the constructor (a general good practice in programming is that constructors shouldn’t have side-effects).

In the rare cases where a constructor really needs a dependency, it’s always possible to fall back to Angular’s built-in pattern of declaring dependencies in the constructor.

All the nomenclature can be a bit confusing, so let’s do a recap:
* Singleton Service: An Angular service that will be instantiated at most once in the entire lifecycle of the application.
* Service Singleton: An instance of a Singleton Service.
* Singleton Proxy: An object that relays method calls to a Service Singleton instance.
== Application Lifecycle ==
When the application is launched, the contents of [[#index.html|index.html]] are rendered on screen. This file is intentionally concise because all the flare is added by Javascript, and the splash screen will be covering the application UI until it has fully started. If you are developing in the browser, this will be a blank screen for you given that the splash screen is not available on the web. We are not targeting browsers in production, so it’s acceptable to have this behaviour during development.

Before the UI is rendered, the startup process will take place. First, Angular will instantiate <code>AppModule</code> and all the imported modules (features, addons, etc.), and then it will execute the initializers (this includes all the initializers, not only the ones declared under [[#core.2Finitializers.2F|core/initializers/]]). In our application, we have overriden [https://angular.io/api/core/ApplicationInitStatus Angular’s initialisation service] to get a hold of the root injector so that we can safely use the [[#Service_singletons|Service Singletons]] pattern within initializers. However, we should avoid this pattern within constructors, because those can be called during the instantiation phase.

Once the application has finished starting up, the router will resolve the active route and the corresponding page component will be rendered. At this point, the splash screen will be hidden and the app is interactive.

[[File:Application Lifecycle.jpg]]
== Testing ==
There are two types of tests in the mobile app.
=== Unit ===
Unit tests are written in JavaScript using [https://jestjs.io/ jest]. If you want to create a new one, jest is already configured and you only need to create a file ending with ''.test.ts'' within the project. If you’re going to do so, remember to follow the [[#Test_files|file location conventions]].

You can run the entire test suite using the npm test command. If you are using VSCode, you can also use the debugger to [https://github.com/moodlehq/moodleapp/blob/integration/.vscode/launch.json run preconfigured test tasks] in the current file or the entire project (using F5 with the default keybindings). This will allow you to use breakpoints and other advanced debugging tools.

You can write standard jest tests for the most part, but something to keep in mind is that the codebase relies heavily on [[#Service_singletons|Service Singletons]]. So you will need to mock any instances that are used in the code you’re testing.

You can learn more about this in the [[Unit testing for the Moodle App]] page.
=== Acceptance ===
Acceptance tests are written in [https://en.wikipedia.org/wiki/Cucumber_(software)#Gherkin_language Gherkin] using [[Acceptance testing|Behat]]. These are run against the full application with a real Moodle site, so they are more heavy-handed and will take longer to run. But they are also much more realistic than unit tests.

If you are using [https://github.com/moodlehq/moodle-docker moodle-docker], you can configure it to [https://github.com/moodlehq/moodle-docker#use-containers-for-running-behat-tests-for-the-mobile-app run the tests from your local copy of the application]. Keep in mind that doing this will run the app on a docker image, and expose the dev server to your machine. So you shouldn’t be running <code>npm start</code> or any other commands launching a dev server while docker is running, or you’ll have two instances running and that can cause some problems.

In order to run your Behat tests, they need to be installed in the Moodle site. You can automate this process by running the <code>npx gulp behat</code> command in the app folder, which will create a local plugin containing your application tests. This uses the environment variables from moodle-docker, if you're not using it you can also configure this by setting the <code>MOODLE_APP_BEHAT_PLUGIN_PATH</code> variable. If you want to keep them up to date every time you change the test files, you can run <code>npx gulp watch-behat</code> (this is already done when developing locally, but if you're serving the app with moodle-docker you'll need to run this from your local machine).

You can write standard Behat tests for the most part, but there are some steps specific for the Moodle App that you should use instead of the ones for the Moodle LMS.

You can learn more about this in the [[Acceptance testing for the Moodle App]] page.
== See also ==
* [[Moodle App Scripts: gulp push]]
* [[Moodle App Accessibility]]
* [[Moodle App Deep Linking]]
* [[Translating the Moodle App]]
[[Category: Mobile]]
[[Category: Moodle App Ionic 5]]

Acceptance testing for the Moodle App

2022-01-13T09:45:56Z

Dpalou: /* Debugging tests */

{{Moodle App (Ionic 5)}}
In order to run tests that carry out automated functionality testing for the Moodle App, you can write [[Acceptance testing|Acceptance tests]]. This can be useful if you want to test plugins that are compatible with the app, or you're contributing to the app core. Behat tests for the app work the same way as tests for Moodle core, but they are not run as part of a normal Behat execution and there are some differences that we'll go through in this page.

A key point is that these tests are run using the Moodle Behat infrastructure, and don't depend only on the app codebase. Therefore, you will need a Moodle development setup as described in [[Setting up development environment]].

The main advantages of this approach are:
* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

== Installation ==
In order to run tests for the app, you will need to run both a Moodle site and the Moodle App.

The Moodle site should be version 3.9.7+, 3.10.4+ or newer (3.11, 4.0, etc.). You also need to install the [https://github.com/moodlehq/moodle-local_moodlemobileapp/ local_moodlemobileapp] plugin, using the version that corresponds with the version of the Moodle App that you're testing on. If you have tests for an older version, you can read the [[#Upgrading_tests_from_an_older_version|Upgrading tests from an older version]] section.

We recommend that you use [https://github.com/moodlehq/moodle-docker#use-containers-for-running-behat-tests-for-the-mobile-app moodle-docker], because it's configured to run mobile tests and you can skip reading this entire section. You won't even need to clone the app repository.

Nevertheless, if you still have to run the projects in your local machine, you can read the following instructions.
=== Configuring the Moodle site ===
You can learn how to run a Moodle site locally in [[Setting up development environment]].

Remember to install the [https://github.com/moodlehq/moodle-local_moodlemobileapp/ local_moodlemobileapp] plugin with the same version that you're using for the mobile app.
=== Configuring the Moodle App ===
If you are going to modify the application code, you can learn how to run it locally in [[Setting up your development environment for the Moodle App]]. You only need to run the application in a browser, so you can skip the instructions for Android/iOS. Make sure to launch the application on the testing environment, running <code>npm run serve:test</code>.

If you only intend to run the app with the goal of executing Behat tests, you can use [[Moodle App Docker Images|the Docker images for the Mobile App]]. Again, make sure that you're running them on the testing environment using the <code>-test</code> suffix.

However you set up the environment, if you change the version of the app you'll need to re-run the Behat init command so that your Moodle site knows about it.
=== Configuring Behat ===
In order to enable app testing, you need to add the following configuration to your site's <code>config.php</code> file:
<syntaxhighlight lang="php">
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</syntaxhighlight>
The url you use here must be reachable by your Moodle site, and the application needs to be served at this url when running tests and also when you initialise the Behat environment.

The Moodle App [[Using the Moodle App in a browser|only works in Chromium-based browsers]], so mobile tests will be ignored if you are using any other browser. You can learn how to configure the browser used in your tests in the [[Running acceptance test]] page.

If everything is configured properly, you should see "Configured app tests for version X.X.X" after running <code>admin/tool/behat/cli/init.php</code>.
== Running Behat ==
To run mobile tests in Behat, simply launch Behat in the usual way. The app tests all have the <code>@app</code> tag, so if you want to run all the mobile tests you can use <code>--tags=@app</code>.

It is OK to combine mobile and web tests in the same run.
== Writing tests ==
This page assumes you already know all about [[Writing acceptance tests]] in general.
=== Test structure ===
Mobile app test scenarios should be marked <code>@app</code> and <code>@javascript</code> in addition to any other tags.

You are writing a normal Behat test and this is likely to require background steps, such as creating courses, users, groups, etc.
=== Start the app ===
When you want to get started testing the application, you can use the following step to launch the application:
<syntaxhighlight lang="gherkin">
Given I enter the app
</syntaxhighlight>
This will:
* Set up all the Moodle server settings to allow the Moodle App to connect.
* Restart the browser, this is needed to ensure that it doesn't use data from previous runs.
* Set the browser to a suitable phone size (you can change it with other steps if you want a tablet or a different size).
* Open the app in the test browser.
* Inject the necessary JavaScript code to support Behat testing.
* Skip the onboarding and enter the site url in the initial screens of the app, if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be at the login screen. If you logged in earlier, you will be at the start page.

You can also use this step if you are already using the app and it will restart it.
=== Log in to the app ===
To log in, you can use the following step:
<syntaxhighlight lang="gherkin">
When I log in as "student"
</syntaxhighlight>
This is the same step that's used to log into standard Moodle, and it works in the app as well. You should have created the user in background steps, and it will log in using the text as both username and password.

You will then be left at the start page.
=== Standard steps ===
Technically, you can use any standard Behat action in the app. However, most of them will probably not work as you expect because the app runs on a different environment. It is still a website, but it's built using [https://ionicframework.com/docs/ Ionic Framework].

One important problem is that the app has a complex DOM, and previous pages that are "back" from your current page may still be present in the DOM. Which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

Another issue is that Ionic relies heavily on [https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM the Shadow DOM], and most steps in standard Moodle are not prepared to handle that.

For these and other reasons, there are some steps that have been implemented specifically for the app. You can distinguish them from others because most of them end with "in the app".

Having said that, here's a list of steps that work and you can use reliably.
* Any step you normally need to set up information in Moodle — For example, creating courses, users, etc.
* <code>I change viewport size to "{width}x{height}"</code> — You can use this step to simulate switching between portrait and landscape formats.
* <code>I pause</code> — This step works and it is very useful to debug your scenario.
=== Actions ===
<syntaxhighlight lang="gherkin">
When I press "Course 1" in the app
</syntaxhighlight>
This will click an element found using accessibility rules, so it could be visible text, content inside <code>aria-label</code>, content described by <code>ara-labelledby</code>, etc. It should work for links, buttons and other clickable elements.
<syntaxhighlight lang="gherkin">
When I press "Course 1" near "Unique text" in the app
</syntaxhighlight>
You can use this step to narrow matches if the text you're providing is duplicated throughout the page.

The second value, "Unique text" in this example, should be unique on the page. Otherwise, you may have issues finding the element that you seek. The system will press the element matching your text that is nearest to the one found using the unique text.

Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate element before you get to a shared ancestor with the unique text.
<syntaxhighlight lang="gherkin">
When I select "Item 1" in the app
When I select "Item 1" near "Unique text" in the app
When I unselect "Item 1" in the app
When I unselect "Item 1" near "Unique text" in the app
</syntaxhighlight>
You can use these steps to select or unselect radio buttons, check boxes, and such.

You could use the previous <code>I press</code> step as well, but in some cases you will notice that it doesn't work as you expect. This is due to some internal quirks of how Ionic renders these components, so prefer using this specific steps where possible.
<syntaxhighlight lang="gherkin">
When I set the field "field name" to "text value" in the app
When I set the field "field name" near "Unique text" to "text value" in the app
</syntaxhighlight>
This sets a text field with the given value. The same rules will apply to find the input element as for clicking, so using the input name will not suffice. This is in order to encourage accessibility best practices. The only difference with the previous step is that this only matches fillable elements such as <code><input></code>, <code><textarea></code> and elements with <code>contenteditable="true"</code>.
<syntaxhighlight lang="gherkin">
When I press the back button in the app
When I press the more menu button in the app
When I press the page menu button in the app
When I press the user menu button in the app
</syntaxhighlight>
These steps will press, respectively:
* The '''back button''' — This is the left pointing arrow at top left of the app.
* The '''more menu''' button — This is the icon with at bottom right of the app.
* The '''page menu''' button, if present — This is the icon with the three dots at top right of the app.
* The '''user menu''' button, if present — This is the avatar button at top right of the app present on navigation level 1.

<syntaxhighlight lang="gherkin">
When I switch to the browser tab opened by the app
When I close the browser tab opened by the app
</syntaxhighlight>
These two steps are necessary if you want to test the transition between the app and a browser.

For example, after pressing "Open in browser" you can use the first step above, and you will be able to use normal Moodle Behat steps to work in the browser tab. Once you're finished, you can use the second step to go back to the app.
=== Assertions ===
Like actions, there are some Behat assertions that are specific to the app.
<syntaxhighlight lang="gherkin">
Then I should find "Course 1" in the app
Then I should find "Course 1" near "Unique text" in the app
Then I should not find "Course 1" in the app
Then I should not find "Course 1" near "Unique text" in the app
</syntaxhighlight>
These steps can be used to assert that the specified text exists somewhere in the app.

Notice that the standard <code>I should see</code> step may not work in the app because of the Shadow DOM. This step will also search using accessibility rules, so text within <code>aria-label</code> or described with <code>aria-labelledby</code> will work as well.
<syntaxhighlight lang="gherkin">
Then the header should be "Course 1" in the app
</syntaxhighlight>
This checks the text of the current page header. It must be an exact match for the specified text.

You could have used the <code>I should find</code> step described previously, but this allows you to specifically check the header as opposed to anything in the page.
<syntaxhighlight lang="gherkin">
Then "Item 1" should be selected in the app
Then "Item 1" near "Unique text" should be selected in the app
Then "Item 1" should not be selected in the app
Then "Item 1" near "Unique text" should not be selected in the app
</syntaxhighlight>
You can use these steps to assert whether radio buttons, check boxes, and such are selected or not.
=== Leaving the app ===
If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page. For example, use <code>I am on site homepage</code> or <code>I am on "Course 1" course homepage</code>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.
=== A complete example ===
This example is a complete feature file that loads the app, opens a course, and asserts that the app is showing the course page:
<syntaxhighlight lang="gherkin">
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student |
And the following "course enrolments" exist:
| user | course | role |
| student | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</syntaxhighlight>
You can find more complex examples looking at the [https://github.com/moodlehq/moodle-local_moodlemobileapp tests for the app core].
== Limitations ==
Using this approach, there are some limitations you should be aware of:
* Lack of native functionality — Fundamentally, it is not possible to test behaviour specific to native devices because tests are run in a browser.
* Missing functionality — There are some known limitations and unsupported features, for example there is currently no obvious way to attach files. Some of these are possible, but they haven't been implemented yet. If something is missing for your use-case, you can submit feature requests in [https://tracker.moodle.org/browse/MOBILE the tracker] using the <code>Behat</code> component.
== Advanced ==
=== Versioning ===
Behat tests can relate to particular versions of the mobile app. For these situations, there are two types of tags you can add to your scenario or feature:
* <code>@app_from{version}</code> — These will be included in every app matching the specified version and newer.
* <code>@app_upto{version}</code> — These will be included in every app matching the specified version and older.

You can use two-digit or three-digit version numbers. For example, you could use <code>@app_from4.0</code> or <code>@app_upto3.9.5</code>.

After changing the app version used for testing, make sure you re-run Behat init. It is the initialisation process that stores which version of the app you're using.
=== Testing against multiple app versions ===
If you need to run tests against multiple versions of the app, you can do it in two ways:
# Update the code in the app workspace by checking out a different version.
# Maintain multiple copies of the mobile app workspace and switch between them by changing <code>config.php</code>.

In both cases, you'll need to re-run the Behat init command and run the tests again.

Unfortunately, the only way to run this in parallel is to have separate Moodle installations with their own configurations.
=== Debugging tests ===
If you insert a pause into your test and open the developer tools, you can debug the application like you would during development. You can learn how to do that in [[Using the Moodle App in a browser]].

Additionally, you can see log information in the console about which Behat steps have been carried out so far, and whether Behat is waiting for anything. Here is an example:
<syntaxhighlight lang="bash">
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</syntaxhighlight>
While the test is paused, you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. The commands are available in a global object called <code>behat</code>. Here are some examples:
<syntaxhighlight lang="javascript">
behat.setField('Password', 'student2');
behat.press('Log in', 'Forgotten');
behat.pressStandard('back');
</syntaxhighlight>
There are more functions in the object; try using the browser's autocomplete to see the options, or look at the source in [https://github.com/moodlehq/moodle-local_moodlemobileapp/blob/master/tests/behat/app_behat_runtime.js app_behat_runtime.js].

If you're using <code>moodle-docker</code>, remember that you can interact with the browser [https://github.com/moodlehq/moodle-docker#using-vnc-to-view-behat-tests using VNC]. With a VNC client you can view in real-time what behat is doing in the browser.
=== Writing custom steps ===
If you find something missing to test your code, you can always implement custom steps.

If you're writing a plugin, you can include a new class under <code>tests/behat/behat_{youpluginname}.php</code>. If you're working on application code, you can always update [https://github.com/moodlehq/moodle-local_moodlemobileapp/blob/master/tests/behat/behat_app.php behat_app.php] as well.

You can learn more about writing custom steps in the [[Writing new acceptance test step definitions]] page, and if you want to see how the steps that are specific to the app work, you should look into [https://github.com/moodlehq/moodle-local_moodlemobileapp/blob/master/tests/behat/behat_app.php behat_app.php] and [https://github.com/moodlehq/moodle-local_moodlemobileapp/blob/master/tests/behat/app_behat_runtime.js app_behat_runtime.js].
== Upgrading tests from an older version ==
If you wrote tests before the app started using Ionic 5 (in version 3.9.5), it is possible that your tests are not working any longer. This guide has been rewritten with the latest information, so make sure to read the rest of the document to see what changed.

In general though, upgrading your current tests should be mostly straightforward. Here are some overall things to keep in mind:
* Ionic 5 starts using [https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM the Shadow DOM], and that's the source of many issues for the previous version of the Behat tests. The built-in steps have been rewritten to keep that in mind, and mostly should work the same way. One important difference is that they look for content using accessibility rules, so some of your previous assumptions may not be working.
* Before this update, it was safe to use the standard <code>I should see</code> step. But given the problems mentioned, it is likely that it breaks down in many situations. Instead, you should use the new <code>I should find ... in the app</code> steps.
* Similar to the last point, some radio inputs and checkboxes that worked before are broken. You should be able to use the new <code>I select ... in the app</code> steps instead.
* If you were relying in xpath or css selectors before, they will probably not work anymore. Even if you try to patch them, these selectors don't pierce through the Shadow DOM. In any case, it's always better to use accessible locators in your test like a real user would, so you can use this opportunity to improve accessibility in your plugin.
* Pay special attention to any assertions such as <code>should not exist</code> that you have in your tests. These assertions will not fail, because the elements won't be found. But if you get an eventual bug when something is shown that shouldn't, those steps will probably not pick it up because the locators may have changed.
* If you were running your tests in CI, there is a new dependency even if you're only testing a plugin and not running the application tests. The test definitions have been moved from core to the [https://github.com/moodlehq/moodle-local_moodlemobileapp/ local_moodlemobileapp] plugin, and you should have it installed in your Moodle site running the tests. This was done in order to decouple application code from the core.

If you also need to upgrade your plugin, and not just the tests, check out the [[Adapt your Mobile plugins to Ionic 5]] page.
== Troubleshooting ==
=== General advice ===
If you are stuck with an error and you can't find a way to continue, here's a list of things you can do:
* Make sure you added <code>$CFG->behat_ionic_wwwroot = "http://localhost:8100";</code> (or equivalent) to your <code>config.php</code> file, and that url is reachable from the host where your Moodle site is running.
* Remember when you need to re-run <code>admin/tool/behat/cli/init.php</code>, and make sure that you see "Configured app tests for version X.X.X". When in doubt, just run it again; it may fix your problem.
* It is possible that your tests break if you're using an unstable version of the app. Try to use stable versions using the <code>master</code> branch if you're working with the source code or tagged releases if you're using Docker.
* Mobile Behat tests don't work well with XDebug, so if you're using it, turn it off in <code>php.ini</code> while running the tests. Also, remember to restart Apache if necessary.
=== Unable to load app version from http://moodleapp:8100/config.json ===
This message appears when the Moodle site is not able to reach the app. Make sure that the url is available from the host you're running the Behat commands from. Also make sure that the app is actually running at the specified url.

It's ok if the actual <code>/config.json</code> url doesn't work, that's actually a remnant from legacy code. The url that Moodle is actually looking for is <code>/assets/env.json</code>.
=== The plugins required by this course could not be loaded correctly... ===
This means either some activity on the course is not adapted to support the moodle app or there is a timeout in the request to your behat site.

To clear the timeout message, open the app in your [[Using_the_Moodle_App_in_a_browser|development browser]], open the Inspector, open the Application tab, select Clear storage, press Clear site data, close Inspector, close the tab with mobile site, re-open mobile site in new tab and log in. Then in a separate tab, log in to your behat site (you can find the url in <code>$CFG->behat_wwwroot</code> within your <code>config.php</code> file) and make sure you can get into the course without seeing the error.
=== Fatal error: Maximum execution time of 30 seconds exceeded in... ===
This means that your local site has not been updated/visited since an upgrade. Just go to your local behat site (you can find the url in <code>$CFG->behat_wwwroot</code> within your <code>config.php</code> file), log in as admin and run notifications, then visit a course. Do this step often to avoid timeouts!
=== Test fails because of the browser language ===
If your operating system is in a different language than English, the tests may fail.

Chrome does not have an easy way to force the browser language to English, so the best way to solve the issue is forcing the app default language to English.

To do so, just set the <code>forcedefaultlanguage</code> attribute to <code>"en"</code> in your <code>moodle.config.json</code> file in the app.
=== Application build gets killed without any error information ===
In some situations, it is possible that you see <code>Killed</code> in the console and a command suddenly stops without any further information. In these situations, make sure to check the [[#General_advice|General advice]] section, but it is possible that your computer is running out of memory.

If you are running the scripts inside of a Docker container, make sure that Docker is allocated enough memory. If you are using Docker desktop (for example, on a Mac), you can inspect these settings under Preferences > Resources > Advanced > Memory.
=== [Mac] running moodle-docker commands show grep usage options and do nothing else ===
This is [https://github.com/moodlehq/moodle-docker/issues/188 a known issue] in moodle-docker for Mac. The workaround for now is just to explicitly initialize the <code>MOODLE_DOCKER_APP_RUNTIME</code> variable in your local environment.
[[Category: Quality Assurance]]
[[Category: Behat]]
[[Category: Mobile]]
[[Category: Moodle App Ionic 5]]

Unit testing for the Moodle App

2021-11-08T08:12:40Z

Dpalou: The mock function has been modified, docs have been updated to match the new parameters.

{{Moodle App (Ionic 5)}}
Unit tests are written in JavaScript using [https://jestjs.io/ Jest]. If you want to create a new one, Jest is already configured and you only need to create a file ending with <code>.test.ts</code> within the project. If you’re going to do so, remember to follow the [[Moodle App Development Guide#Test_files|file location conventions]].
== Running tests ==
The easiest way to run the entire test suite is to execute the <code>npm test</code> command. This will run all the tests in the project. If you want to look at code coverage, you can run <code>npm run test:coverage</code>.

You can also watch changes in your codebase to rerun tests using the <code>npm run test:watch</code> command. In combination with the <code>--filter</code> flag, you can use this to work on a file while you see how your changes affect the tests. But keep in mind that this will be a partial match. For example, if you are working on <code>foobar.ts</code> and you have tests in <code>foobar.test.ts</code>, you can run <code>npm run test:watch --filter foobar</code>, but this will also run tests from <code>foobar-somethingelse.test.ts</code>.

If you are using VSCode, you can use [https://code.visualstudio.com/Docs/editor/debugging the built-in debugger] to run your tests and stop at breakpoints. The project comes with two tasks preconfigured:
* “Jest All” will run your entire test suite. It’s the equivalent of running <code>npm test</code> from the command line.
* “Jest Current File” will run the test of the file you have opened in the editor. Like the <code>--watch</code> filter, this will be a partial match based on the file name.

If you are using the default key bindings, these can be re-run automatically pressing the F5 key.
== Testing plain TypeScript ==
When you are writing tests, a good part of those will be testing plain TypeScript code. You can use all the [https://jestjs.io/docs/using-matchers common techniques used in Jest], and we also offer a couple of helpers.

If you need to create a mock object, you can use the <code>mock</code> helper. This function creates a new object with mock properties and methods. You can use an existing instance, overriding some of its properties and methods if needed, or you can create a new object with only the properties and methods you want.

For example, let’s say we have the following classes:
<syntaxhighlight lang="typescript">
class User {

constructor(public name: string) {}

greet(): void {
// Method implementation
}

}

class Greeter {

sayHello(user: User): string {
user.greet();

return `${user.name} was greeted.`;
}

}
</syntaxhighlight>
If you want to write a test for the <code>sayHello</code> method, you need an instance of <code>User</code>. But maybe you don’t want to use a real user because you want to test the <code>Greeter</code> class in isolation.

Using the <code>mock</code> helper, you can write the following test:
<syntaxhighlight lang="typescript">
it('Greets users', () => {
const user = mock<User>({ name: 'John' }, ['greet']);
const greeter = new Greeter();
const result = greeter.sayHello(user);

expect(result).toEqual('John was greeted.');
expect(user.greet).toHaveBeenCalled();
});
</syntaxhighlight>
Notice how we used the <code>mock</code> helper to create a mock that is properly typed as a <code>User</code>, we indicated that we want to mock the “greet” method, and we initialised the mock instance to have a name of “John”.
== Testing services ==
If you are testing some code that uses [[Moodle App Development Guide#Service_Singletons|Service Singletons]], it is likely that you want to mock some of them. You can achieve it by using the <code>mockSingleton</code> helper. This method takes a Service Singleton and creates a mock for the instance underneath, mocking the methods and properties that you specify along the way.

For example, let’s say that you have the following test:
<syntaxhighlight lang="typescript">
it('App provider checks current platform', () => {
const appService = new CoreAppProvider();

expect(appService.isAndroid()).toBe(true);
expect(appService.isIOS()).toBe(false);
});
</syntaxhighlight>
When you run it, it will fail because the testing platform is neither Android or iOS. You can make the test pass by providing a mock of the <code>Platform</code> singleton that uses the platform of your choice:
<syntaxhighlight lang="typescript">
it('App provider checks current platform', () => {
const platforms = ['cordova', 'android'];
const appService = new CoreAppProvider();

mockSingleton(Platform, {
is: platform => platforms.includes(platform),
});

expect(appService.isAndroid()).toBe(true);
expect(appService.isIOS()).toBe(false);
});
</syntaxhighlight>
Other than preparing the environment, this can also be useful to assert that other services have been used as expected. As you saw in this last example, the <code>mockSingleton</code> method can be used to mock functions without needing to provide an explicit implementation. It uses the same api as the <code>mock</code> helper we introduced in the previous section.

For example, in the following test you can see how we assert that copying text to the clipboard actually calls the native method and displays a confirmation message to the user:
<syntaxhighlight lang="typescript">
it('Copies data to clipboard', async () => {
// Arrange.
const domUtils = new CoreUtilsProvider(mock<NgZone>());

mockSingleton(Clipboard, ['copy']);
mockSingleton(CoreDomUtils, ['showToast']);

// Act.
await domUtils.copyToClipboard('Foo bar');

// Assert.
expect(Clipboard.copy).toHaveBeenCalledWith('Foo bar');
expect(CoreDomUtils.showToast).toHaveBeenCalledWith('core.copiedtoclipboard', true);
});
</syntaxhighlight>
Most services will be instantiated properly without mocks, but sometimes you may see the error “XX is not a function”, or some service property that is undefined. This happens because if it’s not possible to instantiate a service with an empty constructor, it will be provided as an empty object by default. If that happens, you just need to mock the methods and properties that are used in your test. Some basic services like <code>Platform</code> and <code>Network</code> already come with some basic mocks, but they are not exhaustive.
== Testing components ==
Angular components have a strong graphical part, but that doesn’t mean that you can’t test their logic and markup rendering using unit tests with Jest. You can follow [https://angular.io/guide/testing-components-scenarios Angular’s best practices for testing components], and we also provide a couple of helpers that make things easier.

Let’s say you want to test the following component that render a list of user names:
<syntaxhighlight lang="typescript">
@Component({
selector: 'users-list',
template: `
<h1>Users List</h1>
<ul>
<li *ngFor="let user of users">{{ user }}</li>
</ul>
`,
})
export class UsersListComponent {

@Input() users: string[] = [];

}
</syntaxhighlight>
If the component is simple enough that you don’t need to provide any inputs, you can use the <code>renderComponent</code> helper:
<syntaxhighlight lang="typescript">
it('Renders a header', async () => {
const fixture = await renderComponent(UsersListComponent);
const header = fixture.nativeElement.querySelector('h1');

expect(header).not.toBeNull();
expect(header.textContent).toBe('Users List');
});
</syntaxhighlight>
In the more common scenario that you need to provide inputs, you can use the <code>renderTemplate</code> helper:
<syntaxhighlight lang="typescript">
it('Renders a list of users', async () => {
const fixture = await renderTemplate(
UsersListComponent,
`<users-list [users]="['John', 'Amy']"></users-list>`,
);
const list = fixture.nativeElement.querySelector('ul');

expect(list).not.toBeNull();
expect(list.children).toHaveLength(2);
expect(list.children[0].textContent).toEqual('John');
expect(list.children[1].textContent).toEqual('Amy');
});
</syntaxhighlight>
You can also achieve the same result the <code>renderWrapperComponent</code> helper:
<syntaxhighlight lang="typescript">
it('Renders a list of users', async () => {
const fixture = await renderWrapperComponent(
UsersListComponent,
'users-list',
{ users: ['John', 'Amy'] },
);
const list = fixture.nativeElement.querySelector('ul');

expect(list).not.toBeNull();
expect(list.children).toHaveLength(2);
expect(list.children[0].textContent).toEqual('John');
expect(list.children[1].textContent).toEqual('Amy');
});
</syntaxhighlight>
== What about integration tests? ==
Although this guide talks about unit tests, we don’t follow the strict definition of a unit test (which is that a unit test should test a single unit in isolation).

We often write tests where multiple files (or “units”) are involved, and sometimes that can be desirable because it is closer to how the app will behave in production. Technically, those would be considered integration tests, but you can use the same principles and techniques introduced in this document.

If you want to write even more realistic tests, that are actually running the complete application and interacting with it like a real user would, you should check out the [[ Acceptance testing for the Moodle App|Acceptance testing for the Moodle App]] page.
[[Category: Mobile]]
[[Category: Moodle App Ionic 5]]

Debugging network requests in the Moodle App

2021-10-06T06:56:30Z

Dpalou: /* Using a Browser */

{{Moodle App (Ionic 5)}}
== Introduction ==
This guide will help you find and report problems with the Moodle App on your site.

It is especially useful for the following problems:
* Unable to log in on your site.
* When you receive one of the following error messages in the app:
** "Can not find data record in database table external_functions".
** "Invalid response value detected".
** "Cannot get course contents".
== Enabling debugging on your Moodle site ==
# Go to Debugging in the Site administration.
# For "Debug messages" select 'DEVELOPER'.
# Tick "Display debug messages".
# Click the 'Save changes' button.

Remember to disable debugging again once you have finished debugging your problem.
== Enabling debugging on the Moodle App ==
# Go to the More tab.
# Go to Settings > General.
# Enable "Display debug messages".

Remember to disable debugging again once you have finished debugging your problem.
== First attempts ==
At this point, you may not need to go further on this guide.

Log out and log in again into your site and try to reproduce the error. Hopefully, with Moodle and app debugging enabled you will see an explanatory message of what is happening.

If you are unable to find a solution, contact a [https://moodle.com/partners/ Moodle Partner] or post in the [https://moodle.org/mod/forum/view.php?id=7798 Moodle for mobile forum] on moodle.org for non-guaranteed community support.
== Setting up the debugging tool ==
=== Using a Browser ===
In your [[Using the Moodle App in a browser|Chromium-based browser]], you can access your site using the hosted versions of the app in [https://master.apps.moodledemo.net master.apps.moodledemo.net] (the latest stable version) and [https://integration.apps.moodledemo.net integration.apps.moodledemo.net].

Once you're using your site, you can open the [https://developer.chrome.com/docs/devtools/network/ Network panel] of the developer tools and inspect requests. If you're only interested in web service requests, [https://developer.chrome.com/docs/devtools/network/#filter you can filter] writing <code>.php</code> in the filter input.
=== Using a mobile device or emulator ===
If you are using a native device, keep in mind that some requests are not executed through the webview and you won't be able to see them in the network inspector of your developer tools. Instead, you'll have to use native tools the debug the requests.

For example, in Android you can use [https://developer.android.com/studio/profile/network-profiler the Network Profiler].
=== General strategy ===
Here's how to debug web service errors:
# Ignore requests that don’t start with <code>token.php</code> or <code>server.php</code>.
# Once you have selected a request you want to inspect, open the "Response" tab and check if you see an error.
# If you don't understand how to fix the error, you can search in [[:en:Moodle Mobile FAQ|Moodle Mobile FAQ]] to check if there is a known solution.
# If you are unable to find a solution, contact a [https://moodle.com/partners/ Moodle Partner] or post in the [https://moodle.org/mod/forum/view.php?id=7798 Moodle for mobile forum] on moodle.org for non-guaranteed community support.
== Troubleshooting ==
=== How to log into a site configured to use browser or embedded authentication ===
You can execute the following in the JavaScript console:
<syntaxhighlight lang="javascript">
window.handleOpenURL("moodlemobile://URL?token=WSTOKEN");
</syntaxhighlight>
You can also launch a normal authentication process (allowing the authentication popup) and capture the redirect to <code>moodlemobile://...</code> created by the <code>admin/tool/mobile/launch.php</code> script and then execute the following in the console:
<syntaxhighlight lang="javascript">
window.handleOpenURL("moodlemobile://token=ABCxNGUxMD........=");
</syntaxhighlight>

Moodle App Plugins Upgrade Guide

2021-06-25T08:10:55Z

Dpalou:

{{Moodle Mobile}}
{{Ionic5}}

==Introduction==

These past few months we've been working on updating the Ionic framework in the mobile app to Ionic 5. As usual, we tried not to change our APIs and components to prevent breaking existing plugins. Unfortunately, Ionic 5 comes with a lot of breaking changes, especially related to templates. This means that your plugins will need to be adapted in order to look good in the version 3.9.5 of the app.

We're still in the process of migrating some features and fixing things, but we've reached a point where we have a stable app that you can use to test your plugins. We've published this webapp so you can test them:

[https://ionic5.apps.moodledemo.net/ Ionic 5 WebApp]

If you prefer to test this in a local environment you can use the ionic5 branch in our repository:

[https://github.com/moodlehq/moodleapp/tree/ionic5 App source code]

==When will the app with Ionic 5 be published?==

We’re planning to publish the app at the end of June. This means you have about 2 months to adapt your plugin.

==My plugin doesn’t use Ionic components or Javascript, do I need to adapt it?==

In that case it’s possible that you don’t need to adapt the plugin to make it work. We recommend you to test the plugin in the Ionic 5 app to check if everything works.

==Supporting both Ionic 3 and Ionic 5==

Your plugin should still support Ionic 3 so it works in devices that haven’t updated the app yet. This can easily be done by checking the value of ''appversioncode'' sent by the app. I uploaded an example applied to the ''choicegroup'' plugin:

[https://github.com/dpalou/moodle-mod_choicegroup/blob/ionic5/classes/output/mobile.php#L52 Choicegroup code]

As you’ll see, I duplicated the JS and the templates so I have a file to support Ionic 3 and a file to support Ionic 5. I decided to name them “ionic3” and “latest”, but you can structure this as you prefer. You can also have a single file with different HTML depending on the appversioncode, that’s up to you.

==Ionic changes==

As commented before, Ionic has changed a lot of their components, directives and utilities.

In the following 2 pages you’ll find most of the changes done by Ionic and how do you need to change your code to make it work in Ionic 5:

https://github.com/ionic-team/ionic-framework/blob/master/BREAKING.md#version-5x

https://github.com/ionic-team/ionic-framework/blob/master/angular/BREAKING.md

Besides the changes in templates, it’s important to notice that all functions related to modals are now asynchronous. This means that if your plugin is displaying a modal in Javascript then you’ll probably need to adapt your code too.

Another important thing to notice is that the text inside an ''<ion-item>'' now should always be inside an ''<ion-label>'', otherwise it might not look good in some cases. E.g.:

<code html>
<ion-item>My text</ion-item></code>

Should now be:

<code html>
<ion-item><ion-label>My text</ion-label></ion-item></code>

Finally, another important change is that now all Ionic tags are components, e.g. ''<ion-label>'' or ''<ion-avatar>''. This means that these tags cannot have another component in them. Some common cases that will need to be modified:

<code html>
<ion-label core-mark-required=”true></code>
now needs to be:
<code html>
<ion-label><span core-mark-required="true"></code>

<code html>
<ion-avatar core-user-avatar …></code>
now needs to be:
<code html>
<core-user-avatar …></code>

==You can now use ES6==

In v3.9.5 we will increase the minimum Android version to use the app. The newer Cordova and Ionic versions only support Android 5.1+ with newer WebViews, so that will also be the requirement of the app.

The new app will require Android 5.1 with WebView 61+. This means that the Javascript for the app can now be developed in ES6 instead of ES5.

Please notice you '''cannot''' use async/await, they aren't part of ES6 and Android WebView 61 doesn't support await.

This means that the app is no longer transpiled to ES5, and that can break your plugin’s Javascript if you’re extending a class. In Ionic 3, when your plugin receives a class it actually receives a function, and that affects the way to extend it. Now your plugin will receive a Javascript class.

E.g. to create a subclass of ''CoreContentLinksModuleIndexHandler'' you had to do:

<code javascript>
function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

// Rest of constructor.
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;</code>

Now it’s done like this:

<code javascript>
class AddonModChoiceGroupLinkHandler extends this.CoreContentLinksModuleIndexHandler {
constructor() {
super('AddonModChoiceGroup', 'choicegroup');

// Rest of constructor.
}
}</code>

==Changes in the app’s code==

We’ve also done some changes to the code of the app. Most of these changes probably won’t affect your plugin, but we still list them all just in case:

* ''<core-icon>'' is now deprecated, please use ''<ion-icon>'' instead. Right now you can use font-awesome icons with ion-icon. However, it still hasn’t been decided whether font awesome will be used in Moodle 4.0 or not, so it might happen that font-awesome is removed from the app in the future.
* To “cross out” an icon using ion-icon now you need to use ''class=”icon-slash”'' instead of ''slash=”true”''.
* The function ''syncOnSites'' from ''CoreSyncBaseProvider'' now expects to receive a function with the parameters already bound. That is, instead of:

<code javascript>
syncOnSites(‘events', this.syncAllEventsFunc.bind(this), [force], siteId);</code>

You should now do:

<code javascript>
syncOnSites(‘events', this.syncAllEventsFunc.bind(this, force), siteId);</code>

* All the delegates that previously supplied an injector parameter to its handlers now no longer do that. E.g. the function ''getComponent()'' in ''CoreUserProfileFieldDelegate'' used to receive an injector as a parameter, now it won’t receive any parameter.
* All the delegates that previously supplied a ''NavController'' parameter to its handlers now no longer do that. E.g. the function ''openCourse()'' in ''CoreCourseFormatDelegate'' will no longer receive the ''NavController'' parameter.
* The handlers registered in ''CoreCourseOptionsDelegate'' now need to return the properties page+pageParams instead of component+componentData. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
* The handlers registered in ''CoreUserDelegate'' have changed a bit. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
** Handlers can now define a ''cacheEnabled'' property (false by default) to cache ''isEnabledForUser'' calls.
** In the function ''isEnabledForUser'', the params ''navOptions'' and ''admOptions'' have been removed.
** ''isEnabledForUser'' is now optional and defaults to true.
** Now they can implement a new function ''isEnabledForCourse'', and this function will receive the ''navOptions'' and ''admOptions''. If not defined defaults to true.
* The function ''prefetchPackage'' in the ''CoreCourseActivityPrefetchHandlerBase'' has changed. If you were using this class to implement your own prefetch handler you might need to update its code.
* ''CoreInitDelegate'' has been deleted. Now the initialization of the app is done via Angular’s ''APP_INITIALIZER''. Please notice that ''APP_INITIALIZER'' cannot and shouldn’t be used by plugins.
* The function ''getAdditionalDownloadableFiles'' in question types now needs to return a list of ''CoreWSExternalFile'', it no longer accepts a list of strings.
* Files stored to be uploaded later using ''CoreFileUploaderProvider'' no longer have an “offline” property, now they’re just instances of ''FileEntry''.
* ''ionViewCanLeave'' function has been renamed to ''canLeave''.
* The ''onchange'' method of the ''Network'' service is now called ''onChange''.

==Is there any example I can look at?==

If you used the app’s code as an example to build your plugin you can do it again. Most of the templates in the app have already been adapted to Ionic 5. You can see the Ionic 5 code in this branch:

[https://github.com/moodlehq/moodleapp/tree/ionic5 App source code]

I also adapted the choicegroup plugin to make it work in ionic5, you can take a look too. This hasn’t been integrated into the plugin yet because I haven’t done thorough testing yet, you can find it here:

[https://github.com/dpalou/moodle-mod_choicegroup/tree/ionic5 Choicegroup plugin]

Moodle App Plugins Development Guide

2021-05-11T14:22:37Z

Dpalou: /* Module plugins: dynamically determine if a feature is supported */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Make your plugin work in Ionic 5==

If you added mobile support to your plugin for the Ionic 3 version of the app (previous to June 2021) you will probably need to make some changes to the plugin to make it look fine in the Ionic 5 version. Please check the following guide for more details on how to do it:

[[Adapt_your_Mobile_plugins_to_Ionic_5|Adapt your Mobile plugins to Ionic 5]]

If you added the mobile support after June 2021 then your plugin was probably tested on Ionic 5 so you probably won't need to do anything.

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = \context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = \mod_certificate_external::issue_certificate($cm->instance);
$certificates = \mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app.

Alternatively, you can use the [https://download.moodle.org/desktop/ Moodle Desktop App] that is based in the master (latest stable) version of the app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

To enable "Developer Tools" in Moodle Desktop (and the Chrome or Chromium browser);
* In MacOS: Cmd + Option + I
* In Windows or Linux: Ctrl + Shift + I

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.
* '''ismenuhandler''': (optional) Supported from the 3.7.1 version of the app. Set it to true if you want your plugin to be displayed in the contextual menu of the course instead of in the top tabs. The contextual menu is displayed when you click in the 3-dots button at the top right of the course.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory):
** title: a language string identifier that was included in the 'lang' section
** icon: the name of an ionic icon. Valid strings are found here: https://infinitered.github.io/ionicons-version-3-search/ and search for ion-md. Do not include the 'md-' in the string. (eg 'md-information-circle' should be 'information-circle')
** class
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''method''' (optional): The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;
* '''supportedfeatures''': (optional) Supported from the 3.6 version of the app. It can be used to specify the supported features of the plugin. Currently the app only uses FEATURE_MOD_ARCHETYPE and FEATURE_NO_VIEW_LINK. It should be an array with feature => value (e.g. FEATURE_NO_VIEW_LINK => true). If you need to calculate this dynamically please see [[Mobile_support_for_plugins#Module_plugins:_dynamically_determine_if_a_feature_is_supported|Module plugins: dynamically determine if a feature is supported]].
* '''coursepagemethod''': (optional) Supported from the 3.8 version of the app. If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML.

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.
* '''fallback''': (optional) Supported from the 3.9.0 version of the app. This option allows you to specify a block to use in the app instead of your block. E.g. you can make the app display the "My overview" block instead of your block in the app by setting: 'fallback' => 'myoverview'. The fallback will only be used if you don't specify a ''method'' and the ''type'' is different than ''title'' or ''prerendered''..

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate
* CoreFilterDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return this in the init method (only for Moodle 3.8 and onwards).

<code php>
return [
'disabled' => true
];</code>

If the Moodle version is older than 3.8, then the init method should return this:

<code php>
return [
'javascript' => 'this.HANDLER_DISABLED'
];</code>

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result;
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

===Implement a module similar to mod_label===

In Moodle 3.8 or higher, if your plugin doesn't support ''FEATURE_NO_VIEW_LINK'' and you don't specify a ''coursepagemethod'' then the module will only display the module description in the course page and it won't be clickable in the app, just like mod_label. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in ''displaydata'').

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the property ''coursepagemethod'' in the mobile.php. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only default HTML.

If you don't want your module to be clickable then you just need to remove the ''method'' from mobile.php. With these 2 changes you can have a module that behaves like mod_label in the app.

===Use Ionic navigation lifecycle functions===

Ionic let pages define some functions that will be called when certain navigation lifecycle events happen. For more info about these functions, see [https://ionicframework.com/blog/navigating-lifecycle-events/ this page].

You can define these functions in your plugin javascript:

<code javascript>
this.ionViewCanLeave = function() {
...
};</code>

So for example you can make your plugin ask for confirmation if the user tries to leave the page when he has some unsaved data.

===Module plugins: dynamically determine if a feature is supported===

In Moodle you can specify if your plugin supports a certain feature, e.g. FEATURE_NO_VIEW_LINK. If your plugin will always support or not a certain feature, then you can use the ''supportedfeatures'' property in mobile.php to specify it ([[Mobile_support_for_plugins#Options_only_for_CoreCourseModuleDelegate|see more documentation about this]]). But if you need to calculate it dynamically then you will have to create a function to calculate it.

This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section above). The Javascript returned by your init method will need to define a function named ''supportsFeature'' that will receive the name of the feature:

<code javascript>
var result = {
supportsFeature: function(featureName) {
...
}
};
result;</code>

Currently the app only uses FEATURE_MOD_ARCHETYPE and FEATURE_NO_VIEW_LINK.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]

Moodle App Plugins Development Guide

2021-05-11T14:21:37Z

Dpalou: /* Options only for CoreCourseModuleDelegate */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Make your plugin work in Ionic 5==

If you added mobile support to your plugin for the Ionic 3 version of the app (previous to June 2021) you will probably need to make some changes to the plugin to make it look fine in the Ionic 5 version. Please check the following guide for more details on how to do it:

[[Adapt_your_Mobile_plugins_to_Ionic_5|Adapt your Mobile plugins to Ionic 5]]

If you added the mobile support after June 2021 then your plugin was probably tested on Ionic 5 so you probably won't need to do anything.

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = \context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = \mod_certificate_external::issue_certificate($cm->instance);
$certificates = \mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app.

Alternatively, you can use the [https://download.moodle.org/desktop/ Moodle Desktop App] that is based in the master (latest stable) version of the app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

To enable "Developer Tools" in Moodle Desktop (and the Chrome or Chromium browser);
* In MacOS: Cmd + Option + I
* In Windows or Linux: Ctrl + Shift + I

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.
* '''ismenuhandler''': (optional) Supported from the 3.7.1 version of the app. Set it to true if you want your plugin to be displayed in the contextual menu of the course instead of in the top tabs. The contextual menu is displayed when you click in the 3-dots button at the top right of the course.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory):
** title: a language string identifier that was included in the 'lang' section
** icon: the name of an ionic icon. Valid strings are found here: https://infinitered.github.io/ionicons-version-3-search/ and search for ion-md. Do not include the 'md-' in the string. (eg 'md-information-circle' should be 'information-circle')
** class
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''method''' (optional): The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;
* '''supportedfeatures''': (optional) Supported from the 3.6 version of the app. It can be used to specify the supported features of the plugin. Currently the app only uses FEATURE_MOD_ARCHETYPE and FEATURE_NO_VIEW_LINK. It should be an array with feature => value (e.g. FEATURE_NO_VIEW_LINK => true). If you need to calculate this dynamically please see [[Mobile_support_for_plugins#Module_plugins:_dynamically_determine_if_a_feature_is_supported|Module plugins: dynamically determine if a feature is supported]].
* '''coursepagemethod''': (optional) Supported from the 3.8 version of the app. If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML.

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.
* '''fallback''': (optional) Supported from the 3.9.0 version of the app. This option allows you to specify a block to use in the app instead of your block. E.g. you can make the app display the "My overview" block instead of your block in the app by setting: 'fallback' => 'myoverview'. The fallback will only be used if you don't specify a ''method'' and the ''type'' is different than ''title'' or ''prerendered''..

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate
* CoreFilterDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return this in the init method (only for Moodle 3.8 and onwards).

<code php>
return [
'disabled' => true
];</code>

If the Moodle version is older than 3.8, then the init method should return this:

<code php>
return [
'javascript' => 'this.HANDLER_DISABLED'
];</code>

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result;
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

===Implement a module similar to mod_label===

In Moodle 3.8 or higher, if your plugin doesn't support ''FEATURE_NO_VIEW_LINK'' and you don't specify a ''coursepagemethod'' then the module will only display the module description in the course page and it won't be clickable in the app, just like mod_label. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in ''displaydata'').

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the property ''coursepagemethod'' in the mobile.php. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only default HTML.

If you don't want your module to be clickable then you just need to remove the ''method'' from mobile.php. With these 2 changes you can have a module that behaves like mod_label in the app.

===Use Ionic navigation lifecycle functions===

Ionic let pages define some functions that will be called when certain navigation lifecycle events happen. For more info about these functions, see [https://ionicframework.com/blog/navigating-lifecycle-events/ this page].

You can define these functions in your plugin javascript:

<code javascript>
this.ionViewCanLeave = function() {
...
};</code>

So for example you can make your plugin ask for confirmation if the user tries to leave the page when he has some unsaved data.

===Module plugins: dynamically determine if a feature is supported===

In Moodle you can specify if your plugin supports a certain feature, e.g. FEATURE_NO_VIEW_LINK. If your plugin will always support or not a certain feature, then you can use the ''supportedfeatures'' property in mobile.php to specify it (see more documentation about this). But if you need to calculate it dynamically then you will have to create a function to calculate it.

This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section above). The Javascript returned by your init method will need to define a function named ''supportsFeature'' that will receive the name of the feature:

<code javascript>
var result = {
supportsFeature: function(featureName) {
...
}
};
result;</code>

Currently the app only uses FEATURE_MOD_ARCHETYPE and FEATURE_NO_VIEW_LINK.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]

Moodle App Plugins Development Guide

2021-05-11T14:19:36Z

Dpalou: /* Advanced features */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Make your plugin work in Ionic 5==

If you added mobile support to your plugin for the Ionic 3 version of the app (previous to June 2021) you will probably need to make some changes to the plugin to make it look fine in the Ionic 5 version. Please check the following guide for more details on how to do it:

[[Adapt_your_Mobile_plugins_to_Ionic_5|Adapt your Mobile plugins to Ionic 5]]

If you added the mobile support after June 2021 then your plugin was probably tested on Ionic 5 so you probably won't need to do anything.

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = \context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = \mod_certificate_external::issue_certificate($cm->instance);
$certificates = \mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app.

Alternatively, you can use the [https://download.moodle.org/desktop/ Moodle Desktop App] that is based in the master (latest stable) version of the app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

To enable "Developer Tools" in Moodle Desktop (and the Chrome or Chromium browser);
* In MacOS: Cmd + Option + I
* In Windows or Linux: Ctrl + Shift + I

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.
* '''ismenuhandler''': (optional) Supported from the 3.7.1 version of the app. Set it to true if you want your plugin to be displayed in the contextual menu of the course instead of in the top tabs. The contextual menu is displayed when you click in the 3-dots button at the top right of the course.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory):
** title: a language string identifier that was included in the 'lang' section
** icon: the name of an ionic icon. Valid strings are found here: https://infinitered.github.io/ionicons-version-3-search/ and search for ion-md. Do not include the 'md-' in the string. (eg 'md-information-circle' should be 'information-circle')
** class
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''method''' (optional): The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;
* '''coursepagemethod''': (optional) Supported from the 3.8 version of the app. If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML.

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.
* '''fallback''': (optional) Supported from the 3.9.0 version of the app. This option allows you to specify a block to use in the app instead of your block. E.g. you can make the app display the "My overview" block instead of your block in the app by setting: 'fallback' => 'myoverview'. The fallback will only be used if you don't specify a ''method'' and the ''type'' is different than ''title'' or ''prerendered''..

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate
* CoreFilterDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return this in the init method (only for Moodle 3.8 and onwards).

<code php>
return [
'disabled' => true
];</code>

If the Moodle version is older than 3.8, then the init method should return this:

<code php>
return [
'javascript' => 'this.HANDLER_DISABLED'
];</code>

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result;
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

===Implement a module similar to mod_label===

In Moodle 3.8 or higher, if your plugin doesn't support ''FEATURE_NO_VIEW_LINK'' and you don't specify a ''coursepagemethod'' then the module will only display the module description in the course page and it won't be clickable in the app, just like mod_label. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in ''displaydata'').

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the property ''coursepagemethod'' in the mobile.php. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only default HTML.

If you don't want your module to be clickable then you just need to remove the ''method'' from mobile.php. With these 2 changes you can have a module that behaves like mod_label in the app.

===Use Ionic navigation lifecycle functions===

Ionic let pages define some functions that will be called when certain navigation lifecycle events happen. For more info about these functions, see [https://ionicframework.com/blog/navigating-lifecycle-events/ this page].

You can define these functions in your plugin javascript:

<code javascript>
this.ionViewCanLeave = function() {
...
};</code>

So for example you can make your plugin ask for confirmation if the user tries to leave the page when he has some unsaved data.

===Module plugins: dynamically determine if a feature is supported===

In Moodle you can specify if your plugin supports a certain feature, e.g. FEATURE_NO_VIEW_LINK. If your plugin will always support or not a certain feature, then you can use the ''supportedfeatures'' property in mobile.php to specify it (see more documentation about this). But if you need to calculate it dynamically then you will have to create a function to calculate it.

This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section above). The Javascript returned by your init method will need to define a function named ''supportsFeature'' that will receive the name of the feature:

<code javascript>
var result = {
supportsFeature: function(featureName) {
...
}
};
result;</code>

Currently the app only uses FEATURE_MOD_ARCHETYPE and FEATURE_NO_VIEW_LINK.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]

Moodle App Plugins Upgrade Guide

2021-04-13T07:10:37Z

Dpalou: /* You can now use ES6 */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Introduction==

These past few months we've been working on updating the Ionic framework in the mobile app to Ionic 5. As usual, we tried not to change our APIs and components to prevent breaking existing plugins. Unfortunately, Ionic 5 comes with a lot of breaking changes, especially related to templates. This means that your plugins will need to be adapted in order to look good in the version 3.9.5 of the app.

We're still in the process of migrating some features and fixing things, but we've reached a point where we have a stable app that you can use to test your plugins. We've published this webapp so you can test them:

[https://ionic5.apps.moodledemo.net/ Ionic 5 WebApp]

If you prefer to test this in a local environment you can use the ionic5 branch in our repository:

[https://github.com/moodlehq/moodleapp/tree/ionic5 App source code]

==When will the app with Ionic 5 be published?==

We’re planning to publish the app at the end of June. This means you have about 2 months to adapt your plugin.

==My plugin doesn’t use Ionic components or Javascript, do I need to adapt it?==

In that case it’s possible that you don’t need to adapt the plugin to make it work. We recommend you to test the plugin in the Ionic 5 app to check if everything works.

==Supporting both Ionic 3 and Ionic 5==

Your plugin should still support Ionic 3 so it works in devices that haven’t updated the app yet. This can easily be done by checking the value of ''appversioncode'' sent by the app. I uploaded an example applied to the ''choicegroup'' plugin:

[https://github.com/dpalou/moodle-mod_choicegroup/blob/ionic5/classes/output/mobile.php#L52 Choicegroup code]

As you’ll see, I duplicated the JS and the templates so I have a file to support Ionic 3 and a file to support Ionic 5. I decided to name them “ionic3” and “latest”, but you can structure this as you prefer. You can also have a single file with different HTML depending on the appversioncode, that’s up to you.

==Ionic changes==

As commented before, Ionic has changed a lot of their components, directives and utilities.

In the following 2 pages you’ll find most of the changes done by Ionic and how do you need to change your code to make it work in Ionic 5:

https://github.com/ionic-team/ionic-framework/blob/master/BREAKING.md#version-5x

https://github.com/ionic-team/ionic-framework/blob/master/angular/BREAKING.md

Besides the changes in templates, it’s important to notice that all functions related to modals are now asynchronous. This means that if your plugin is displaying a modal in Javascript then you’ll probably need to adapt your code too.

Another important thing to notice is that the text inside an ''<ion-item>'' now should always be inside an ''<ion-label>'', otherwise it might not look good in some cases. E.g.:

<code html>
<ion-item>My text</ion-item></code>

Should now be:

<code html>
<ion-item><ion-label>My text</ion-label></ion-item></code>

Finally, another important change is that now all Ionic tags are components, e.g. ''<ion-label>'' or ''<ion-avatar>''. This means that these tags cannot have another component in them. Some common cases that will need to be modified:

<code html>
<ion-label core-mark-required=”true></code>
now needs to be:
<code html>
<ion-label><span core-mark-required="true"></code>

<code html>
<ion-avatar core-user-avatar …></code>
now needs to be:
<code html>
<core-user-avatar …></code>

==You can now use ES6==

In v3.9.5 we will increase the minimum Android version to use the app. The newer Cordova and Ionic versions only support Android 5.1+ with newer WebViews, so that will also be the requirement of the app.

The new app will require Android 5.1 with WebView 61+. This means that the Javascript for the app can now be developed in ES6 instead of ES5.

Please notice you '''cannot''' use async/await, they aren't part of ES6 and Android WebView 61 doesn't support await.

This means that the app is no longer transpiled to ES5, and that can break your plugin’s Javascript if you’re extending a class. In Ionic 3, when your plugin receives a class it actually receives a function, and that affects the way to extend it. Now your plugin will receive a Javascript class.

E.g. to create a subclass of ''CoreContentLinksModuleIndexHandler'' you had to do:

<code javascript>
function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

// Rest of constructor.
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;</code>

Now it’s done like this:

<code javascript>
class AddonModChoiceGroupLinkHandler extends this.CoreContentLinksModuleIndexHandler {
constructor() {
super('AddonModChoiceGroup', 'choicegroup');

// Rest of constructor.
}
}</code>

==Changes in the app’s code==

We’ve also done some changes to the code of the app. Most of these changes probably won’t affect your plugin, but we still list them all just in case:

* ''<core-icon>'' is now deprecated, please use ''<ion-icon>'' instead. Right now you can use font-awesome icons with ion-icon. However, it still hasn’t been decided whether font awesome will be used in Moodle 4.0 or not, so it might happen that font-awesome is removed from the app in the future.
* To “cross out” an icon using ion-icon now you need to use ''class=”icon-slash”'' instead of ''slash=”true”''.
* The function ''syncOnSites'' from ''CoreSyncBaseProvider'' now expects to receive a function with the parameters already bound. That is, instead of:

<code javascript>
syncOnSites(‘events', this.syncAllEventsFunc.bind(this), [force], siteId);</code>

You should now do:

<code javascript>
syncOnSites(‘events', this.syncAllEventsFunc.bind(this, force), siteId);</code>

* All the delegates that previously supplied an injector parameter to its handlers now no longer do that. E.g. the function ''getComponent()'' in ''CoreUserProfileFieldDelegate'' used to receive an injector as a parameter, now it won’t receive any parameter.
* All the delegates that previously supplied a ''NavController'' parameter to its handlers now no longer do that. E.g. the function ''openCourse()'' in ''CoreCourseFormatDelegate'' will no longer receive the ''NavController'' parameter.
* The handlers registered in ''CoreCourseOptionsDelegate'' now need to return the properties page+pageParams instead of component+componentData. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
* The handlers registered in ''CoreUserDelegate'' have changed a bit. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
** Handlers can now define a ''cacheEnabled'' property (false by default) to cache ''isEnabledForUser'' calls.
** In the function ''isEnabledForUser'', the params ''navOptions'' and ''admOptions'' have been removed.
** ''isEnabledForUser'' is now optional and defaults to true.
** Now they can implement a new function ''isEnabledForCourse'', and this function will receive the ''navOptions'' and ''admOptions''. If not defined defaults to true.
* The function ''prefetchPackage'' in the ''CoreCourseActivityPrefetchHandlerBase'' has changed. If you were using this class to implement your own prefetch handler you might need to update its code.
* ''CoreInitDelegate'' has been deleted. Now the initialization of the app is done via Angular’s ''APP_INITIALIZER''. Please notice that ''APP_INITIALIZER'' cannot and shouldn’t be used by plugins.
* The function ''getAdditionalDownloadableFiles'' in question types now needs to return a list of ''CoreWSExternalFile'', it no longer accepts a list of strings.
* Files stored to be uploaded later using ''CoreFileUploaderProvider'' no longer have an “offline” property, now they’re just instances of ''FileEntry''.
* ''ionViewCanLeave'' function has been renamed to ''canLeave''.
* The ''onchange'' method of the ''Network'' service is now called ''onChange''.

==Is there any example I can look at?==

If you used the app’s code as an example to build your plugin you can do it again. Most of the templates in the app have already been adapted to Ionic 5. You can see the Ionic 5 code in this branch:

[https://github.com/moodlehq/moodleapp/tree/ionic5 App source code]

I also adapted the choicegroup plugin to make it work in ionic5, you can take a look too. This hasn’t been integrated into the plugin yet because I haven’t done thorough testing yet, you can find it here:

[https://github.com/dpalou/moodle-mod_choicegroup/tree/ionic5 Choicegroup plugin]

Moodle App Plugins Development Guide

2021-04-06T11:18:48Z

Dpalou:

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Make your plugin work in Ionic 5==

If you added mobile support to your plugin for the Ionic 3 version of the app (previous to June 2021) you will probably need to make some changes to the plugin to make it look fine in the Ionic 5 version. Please check the following guide for more details on how to do it:

[[Adapt_your_Mobile_plugins_to_Ionic_5|Adapt your Mobile plugins to Ionic 5]]

If you added the mobile support after June 2021 then your plugin was probably tested on Ionic 5 so you probably won't need to do anything.

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = \context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = \mod_certificate_external::issue_certificate($cm->instance);
$certificates = \mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app.

Alternatively, you can use the [https://download.moodle.org/desktop/ Moodle Desktop App] that is based in the master (latest stable) version of the app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

To enable "Developer Tools" in Moodle Desktop (and the Chrome or Chromium browser);
* In MacOS: Cmd + Option + I
* In Windows or Linux: Ctrl + Shift + I

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.
* '''ismenuhandler''': (optional) Supported from the 3.7.1 version of the app. Set it to true if you want your plugin to be displayed in the contextual menu of the course instead of in the top tabs. The contextual menu is displayed when you click in the 3-dots button at the top right of the course.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory):
** title: a language string identifier that was included in the 'lang' section
** icon: the name of an ionic icon. Valid strings are found here: https://infinitered.github.io/ionicons-version-3-search/ and search for ion-md. Do not include the 'md-' in the string. (eg 'md-information-circle' should be 'information-circle')
** class
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''method''' (optional): The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;
* '''coursepagemethod''': (optional) Supported from the 3.8 version of the app. If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML.

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.
* '''fallback''': (optional) Supported from the 3.9.0 version of the app. This option allows you to specify a block to use in the app instead of your block. E.g. you can make the app display the "My overview" block instead of your block in the app by setting: 'fallback' => 'myoverview'. The fallback will only be used if you don't specify a ''method'' and the ''type'' is different than ''title'' or ''prerendered''..

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate
* CoreFilterDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return this in the init method (only for Moodle 3.8 and onwards).

<code php>
return [
'disabled' => true
];</code>

If the Moodle version is older than 3.8, then the init method should return this:

<code php>
return [
'javascript' => 'this.HANDLER_DISABLED'
];</code>

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result;
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

===Implement a module similar to mod_label===

In Moodle 3.8 or higher, if your plugin doesn't support ''FEATURE_NO_VIEW_LINK'' and you don't specify a ''coursepagemethod'' then the module will only display the module description in the course page and it won't be clickable in the app, just like mod_label. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in ''displaydata'').

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the property ''coursepagemethod'' in the mobile.php. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only default HTML.

If you don't want your module to be clickable then you just need to remove the ''method'' from mobile.php. With these 2 changes you can have a module that behaves like mod_label in the app.

===Use Ionic navigation lifecycle functions===

Ionic let pages define some functions that will be called when certain navigation lifecycle events happen. For more info about these functions, see [https://ionicframework.com/blog/navigating-lifecycle-events/ this page].

You can define these functions in your plugin javascript:

<code javascript>
this.ionViewCanLeave = function() {
...
};</code>

So for example you can make your plugin ask for confirmation if the user tries to leave the page when he has some unsaved data.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]

Adapt your plugins to Ionic 5

2021-04-06T10:51:23Z

Dpalou: Redirected page to Adapt your Mobile plugins to Ionic 5

#REDIRECT [[Adapt_your_Mobile_plugins_to_Ionic_5]]

Moodle App Plugins Upgrade Guide

2021-04-06T10:50:56Z

Dpalou: Created page with "{{Moodle Mobile}} {{Moodle Mobile 3.5}} ==Introduction== These past few months we've been working on updating the Ionic framework in the mobile app to Ionic 5. As usual, we..."

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Introduction==

These past few months we've been working on updating the Ionic framework in the mobile app to Ionic 5. As usual, we tried not to change our APIs and components to prevent breaking existing plugins. Unfortunately, Ionic 5 comes with a lot of breaking changes, especially related to templates. This means that your plugins will need to be adapted in order to look good in the version 3.9.5 of the app.

We're still in the process of migrating some features and fixing things, but we've reached a point where we have a stable app that you can use to test your plugins. We've published this webapp so you can test them:

[https://ionic5.apps.moodledemo.net/ Ionic 5 WebApp]

If you prefer to test this in a local environment you can use the ionic5 branch in our repository:

[https://github.com/moodlehq/moodleapp/tree/ionic5 App source code]

==When will the app with Ionic 5 be published?==

We’re planning to publish the app at the end of June. This means you have about 2 months to adapt your plugin.

==My plugin doesn’t use Ionic components or Javascript, do I need to adapt it?==

In that case it’s possible that you don’t need to adapt the plugin to make it work. We recommend you to test the plugin in the Ionic 5 app to check if everything works.

==Supporting both Ionic 3 and Ionic 5==

Your plugin should still support Ionic 3 so it works in devices that haven’t updated the app yet. This can easily be done by checking the value of ''appversioncode'' sent by the app. I uploaded an example applied to the ''choicegroup'' plugin:

[https://github.com/dpalou/moodle-mod_choicegroup/blob/ionic5/classes/output/mobile.php#L52 Choicegroup code]

As you’ll see, I duplicated the JS and the templates so I have a file to support Ionic 3 and a file to support Ionic 5. I decided to name them “ionic3” and “latest”, but you can structure this as you prefer. You can also have a single file with different HTML depending on the appversioncode, that’s up to you.

==Ionic changes==

As commented before, Ionic has changed a lot of their components, directives and utilities.

In the following 2 pages you’ll find most of the changes done by Ionic and how do you need to change your code to make it work in Ionic 5:

https://github.com/ionic-team/ionic-framework/blob/master/BREAKING.md#version-5x

https://github.com/ionic-team/ionic-framework/blob/master/angular/BREAKING.md

Besides the changes in templates, it’s important to notice that all functions related to modals are now asynchronous. This means that if your plugin is displaying a modal in Javascript then you’ll probably need to adapt your code too.

Another important thing to notice is that the text inside an ''<ion-item>'' now should always be inside an ''<ion-label>'', otherwise it might not look good in some cases. E.g.:

<code html>
<ion-item>My text</ion-item></code>

Should now be:

<code html>
<ion-item><ion-label>My text</ion-label></ion-item></code>

Finally, another important change is that now all Ionic tags are components, e.g. ''<ion-label>'' or ''<ion-avatar>''. This means that these tags cannot have another component in them. Some common cases that will need to be modified:

<code html>
<ion-label core-mark-required=”true></code>
now needs to be:
<code html>
<ion-label><span core-mark-required="true"></code>

<code html>
<ion-avatar core-user-avatar …></code>
now needs to be:
<code html>
<core-user-avatar …></code>

==You can now use ES6==

In v3.9.5 we will increase the minimum Android version to use the app. The newer Cordova and Ionic versions only support Android 5.1+ with newer WebViews, so that will also be the requirement of the app.

The new app will require Android 5.1 with WebView 61+. This means that the Javascript for the app can now be developed in ES6 instead of ES5. Also, you can use arrow functions since they were introduced in WebView 55 and iOS 10.3.

This means that the app is no longer transpiled to ES5, and that can break your plugin’s Javascript if you’re extending a class. In Ionic 3, when your plugin receives a class it actually receives a function, and that affects the way to extend it. Now your plugin will receive a Javascript class.

E.g. to create a subclass of ''CoreContentLinksModuleIndexHandler'' you had to do:

<code javascript>
function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

// Rest of constructor.
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;</code>

Now it’s done like this:

<code javascript>
class AddonModChoiceGroupLinkHandler extends this.CoreContentLinksModuleIndexHandler {
constructor() {
super('AddonModChoiceGroup', 'choicegroup');

// Rest of constructor.
}
}</code>

==Changes in the app’s code==

We’ve also done some changes to the code of the app. Most of these changes probably won’t affect your plugin, but we still list them all just in case:

* ''<core-icon>'' is now deprecated, please use ''<ion-icon>'' instead. Right now you can use font-awesome icons with ion-icon. However, it still hasn’t been decided whether font awesome will be used in Moodle 4.0 or not, so it might happen that font-awesome is removed from the app in the future.
* To “cross out” an icon using ion-icon now you need to use ''class=”icon-slash”'' instead of ''slash=”true”''.
* The function ''syncOnSites'' from ''CoreSyncBaseProvider'' now expects to receive a function with the parameters already bound. That is, instead of:

<code javascript>
syncOnSites(‘events', this.syncAllEventsFunc.bind(this), [force], siteId);</code>

You should now do:

<code javascript>
syncOnSites(‘events', this.syncAllEventsFunc.bind(this, force), siteId);</code>

* All the delegates that previously supplied an injector parameter to its handlers now no longer do that. E.g. the function ''getComponent()'' in ''CoreUserProfileFieldDelegate'' used to receive an injector as a parameter, now it won’t receive any parameter.
* All the delegates that previously supplied a ''NavController'' parameter to its handlers now no longer do that. E.g. the function ''openCourse()'' in ''CoreCourseFormatDelegate'' will no longer receive the ''NavController'' parameter.
* The handlers registered in ''CoreCourseOptionsDelegate'' now need to return the properties page+pageParams instead of component+componentData. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
* The handlers registered in ''CoreUserDelegate'' have changed a bit. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
** Handlers can now define a ''cacheEnabled'' property (false by default) to cache ''isEnabledForUser'' calls.
** In the function ''isEnabledForUser'', the params ''navOptions'' and ''admOptions'' have been removed.
** ''isEnabledForUser'' is now optional and defaults to true.
** Now they can implement a new function ''isEnabledForCourse'', and this function will receive the ''navOptions'' and ''admOptions''. If not defined defaults to true.
* The function ''prefetchPackage'' in the ''CoreCourseActivityPrefetchHandlerBase'' has changed. If you were using this class to implement your own prefetch handler you might need to update its code.
* ''CoreInitDelegate'' has been deleted. Now the initialization of the app is done via Angular’s ''APP_INITIALIZER''. Please notice that ''APP_INITIALIZER'' cannot and shouldn’t be used by plugins.
* The function ''getAdditionalDownloadableFiles'' in question types now needs to return a list of ''CoreWSExternalFile'', it no longer accepts a list of strings.
* Files stored to be uploaded later using ''CoreFileUploaderProvider'' no longer have an “offline” property, now they’re just instances of ''FileEntry''.
* ''ionViewCanLeave'' function has been renamed to ''canLeave''.
* The ''onchange'' method of the ''Network'' service is now called ''onChange''.

==Is there any example I can look at?==

If you used the app’s code as an example to build your plugin you can do it again. Most of the templates in the app have already been adapted to Ionic 5. You can see the Ionic 5 code in this branch:

[https://github.com/moodlehq/moodleapp/tree/ionic5 App source code]

I also adapted the choicegroup plugin to make it work in ionic5, you can take a look too. This hasn’t been integrated into the plugin yet because I haven’t done thorough testing yet, you can find it here:

[https://github.com/dpalou/moodle-mod_choicegroup/tree/ionic5 Choicegroup plugin]

Adapt your plugins to Ionic 5

2021-04-06T10:45:08Z

Dpalou: /* Is there any example I can look at? */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Introduction==

These past few months we've been working on updating the Ionic framework in the mobile app to Ionic 5. As usual, we tried not to change our APIs and components to prevent breaking existing plugins. Unfortunately, Ionic 5 comes with a lot of breaking changes, especially related to templates. This means that your plugins will need to be adapted in order to look good in the version 3.9.5 of the app.

We're still in the process of migrating some features and fixing things, but we've reached a point where we have a stable app that you can use to test your plugins. We've published this webapp so you can test them:

[https://ionic5.apps.moodledemo.net/ Ionic 5 WebApp]

If you prefer to test this in a local environment you can use the ionic5 branch in our repository:

[https://github.com/moodlehq/moodleapp/tree/ionic5 App source code]

==When will the app with Ionic 5 be published?==

We’re planning to publish the app at the end of June. This means you have about 2 months to adapt your plugin.

==My plugin doesn’t use Ionic components or Javascript, do I need to adapt it?==

In that case it’s possible that you don’t need to adapt the plugin to make it work. We recommend you to test the plugin in the Ionic 5 app to check if everything works.

==Supporting both Ionic 3 and Ionic 5==

Your plugin should still support Ionic 3 so it works in devices that haven’t updated the app yet. This can easily be done by checking the value of ''appversioncode'' sent by the app. I uploaded an example applied to the ''choicegroup'' plugin:

[https://github.com/dpalou/moodle-mod_choicegroup/blob/ionic5/classes/output/mobile.php#L52 Choicegroup code]

As you’ll see, I duplicated the JS and the templates so I have a file to support Ionic 3 and a file to support Ionic 5. I decided to name them “ionic3” and “latest”, but you can structure this as you prefer. You can also have a single file with different HTML depending on the appversioncode, that’s up to you.

==Ionic changes==

As commented before, Ionic has changed a lot of their components, directives and utilities.

In the following 2 pages you’ll find most of the changes done by Ionic and how do you need to change your code to make it work in Ionic 5:

https://github.com/ionic-team/ionic-framework/blob/master/BREAKING.md#version-5x

https://github.com/ionic-team/ionic-framework/blob/master/angular/BREAKING.md

Besides the changes in templates, it’s important to notice that all functions related to modals are now asynchronous. This means that if your plugin is displaying a modal in Javascript then you’ll probably need to adapt your code too.

Another important thing to notice is that the text inside an ''<ion-item>'' now should always be inside an ''<ion-label>'', otherwise it might not look good in some cases. E.g.:

<code html>
<ion-item>My text</ion-item></code>

Should now be:

<code html>
<ion-item><ion-label>My text</ion-label></ion-item></code>

Finally, another important change is that now all Ionic tags are components, e.g. ''<ion-label>'' or ''<ion-avatar>''. This means that these tags cannot have another component in them. Some common cases that will need to be modified:

<code html>
<ion-label core-mark-required=”true></code>
now needs to be:
<code html>
<ion-label><span core-mark-required="true"></code>

<code html>
<ion-avatar core-user-avatar …></code>
now needs to be:
<code html>
<core-user-avatar …></code>

==You can now use ES6==

In v3.9.5 we will increase the minimum Android version to use the app. The newer Cordova and Ionic versions only support Android 5.1+ with newer WebViews, so that will also be the requirement of the app.

The new app will require Android 5.1 with WebView 61+. This means that the Javascript for the app can now be developed in ES6 instead of ES5. Also, you can use arrow functions since they were introduced in WebView 55 and iOS 10.3.

This means that the app is no longer transpiled to ES5, and that can break your plugin’s Javascript if you’re extending a class. In Ionic 3, when your plugin receives a class it actually receives a function, and that affects the way to extend it. Now your plugin will receive a Javascript class.

E.g. to create a subclass of ''CoreContentLinksModuleIndexHandler'' you had to do:

<code javascript>
function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

// Rest of constructor.
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;</code>

Now it’s done like this:

<code javascript>
class AddonModChoiceGroupLinkHandler extends this.CoreContentLinksModuleIndexHandler {
constructor() {
super('AddonModChoiceGroup', 'choicegroup');

// Rest of constructor.
}
}</code>

==Changes in the app’s code==

We’ve also done some changes to the code of the app. Most of these changes probably won’t affect your plugin, but we still list them all just in case:

* ''<core-icon>'' is now deprecated, please use ''<ion-icon>'' instead. Right now you can use font-awesome icons with ion-icon. However, it still hasn’t been decided whether font awesome will be used in Moodle 4.0 or not, so it might happen that font-awesome is removed from the app in the future.
* To “cross out” an icon using ion-icon now you need to use ''class=”icon-slash”'' instead of ''slash=”true”''.
* The function ''syncOnSites'' from ''CoreSyncBaseProvider'' now expects to receive a function with the parameters already bound. That is, instead of:

<code javascript>
syncOnSites(‘events', this.syncAllEventsFunc.bind(this), [force], siteId);</code>

You should now do:

<code javascript>
syncOnSites(‘events', this.syncAllEventsFunc.bind(this, force), siteId);</code>

* All the delegates that previously supplied an injector parameter to its handlers now no longer do that. E.g. the function ''getComponent()'' in ''CoreUserProfileFieldDelegate'' used to receive an injector as a parameter, now it won’t receive any parameter.
* All the delegates that previously supplied a ''NavController'' parameter to its handlers now no longer do that. E.g. the function ''openCourse()'' in ''CoreCourseFormatDelegate'' will no longer receive the ''NavController'' parameter.
* The handlers registered in ''CoreCourseOptionsDelegate'' now need to return the properties page+pageParams instead of component+componentData. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
* The handlers registered in ''CoreUserDelegate'' have changed a bit. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
** Handlers can now define a ''cacheEnabled'' property (false by default) to cache ''isEnabledForUser'' calls.
** In the function ''isEnabledForUser'', the params ''navOptions'' and ''admOptions'' have been removed.
** ''isEnabledForUser'' is now optional and defaults to true.
** Now they can implement a new function ''isEnabledForCourse'', and this function will receive the ''navOptions'' and ''admOptions''. If not defined defaults to true.
* The function ''prefetchPackage'' in the ''CoreCourseActivityPrefetchHandlerBase'' has changed. If you were using this class to implement your own prefetch handler you might need to update its code.
* ''CoreInitDelegate'' has been deleted. Now the initialization of the app is done via Angular’s ''APP_INITIALIZER''. Please notice that ''APP_INITIALIZER'' cannot and shouldn’t be used by plugins.
* The function ''getAdditionalDownloadableFiles'' in question types now needs to return a list of ''CoreWSExternalFile'', it no longer accepts a list of strings.
* Files stored to be uploaded later using ''CoreFileUploaderProvider'' no longer have an “offline” property, now they’re just instances of ''FileEntry''.
* ''ionViewCanLeave'' function has been renamed to ''canLeave''.
* The ''onchange'' method of the ''Network'' service is now called ''onChange''.

==Is there any example I can look at?==

If you used the app’s code as an example to build your plugin you can do it again. Most of the templates in the app have already been adapted to Ionic 5. You can see the Ionic 5 code in this branch:

[https://github.com/moodlehq/moodleapp/tree/ionic5 App source code]

I also adapted the choicegroup plugin to make it work in ionic5, you can take a look too. This hasn’t been integrated into the plugin yet because I haven’t done thorough testing yet, you can find it here:

[https://github.com/dpalou/moodle-mod_choicegroup/tree/ionic5 Choicegroup plugin]

Adapt your plugins to Ionic 5

2021-04-06T10:43:45Z

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Introduction==

These past few months we've been working on updating the Ionic framework in the mobile app to Ionic 5. As usual, we tried not to change our APIs and components to prevent breaking existing plugins. Unfortunately, Ionic 5 comes with a lot of breaking changes, especially related to templates. This means that your plugins will need to be adapted in order to look good in the version 3.9.5 of the app.

We're still in the process of migrating some features and fixing things, but we've reached a point where we have a stable app that you can use to test your plugins. We've published this webapp so you can test them:

[https://ionic5.apps.moodledemo.net/ Ionic 5 WebApp]

If you prefer to test this in a local environment you can use the ionic5 branch in our repository:

[https://github.com/moodlehq/moodleapp/tree/ionic5 App source code]

==When will the app with Ionic 5 be published?==

We’re planning to publish the app at the end of June. This means you have about 2 months to adapt your plugin.

==My plugin doesn’t use Ionic components or Javascript, do I need to adapt it?==

In that case it’s possible that you don’t need to adapt the plugin to make it work. We recommend you to test the plugin in the Ionic 5 app to check if everything works.

==Supporting both Ionic 3 and Ionic 5==

Your plugin should still support Ionic 3 so it works in devices that haven’t updated the app yet. This can easily be done by checking the value of ''appversioncode'' sent by the app. I uploaded an example applied to the ''choicegroup'' plugin:

[https://github.com/dpalou/moodle-mod_choicegroup/blob/ionic5/classes/output/mobile.php#L52 Choicegroup code]

As you’ll see, I duplicated the JS and the templates so I have a file to support Ionic 3 and a file to support Ionic 5. I decided to name them “ionic3” and “latest”, but you can structure this as you prefer. You can also have a single file with different HTML depending on the appversioncode, that’s up to you.

==Ionic changes==

As commented before, Ionic has changed a lot of their components, directives and utilities.

In the following 2 pages you’ll find most of the changes done by Ionic and how do you need to change your code to make it work in Ionic 5:

https://github.com/ionic-team/ionic-framework/blob/master/BREAKING.md#version-5x

https://github.com/ionic-team/ionic-framework/blob/master/angular/BREAKING.md

Besides the changes in templates, it’s important to notice that all functions related to modals are now asynchronous. This means that if your plugin is displaying a modal in Javascript then you’ll probably need to adapt your code too.

Another important thing to notice is that the text inside an ''<ion-item>'' now should always be inside an ''<ion-label>'', otherwise it might not look good in some cases. E.g.:

<code html>
<ion-item>My text</ion-item></code>

Should now be:

<code html>
<ion-item><ion-label>My text</ion-label></ion-item></code>

Finally, another important change is that now all Ionic tags are components, e.g. ''<ion-label>'' or ''<ion-avatar>''. This means that these tags cannot have another component in them. Some common cases that will need to be modified:

<code html>
<ion-label core-mark-required=”true></code>
now needs to be:
<code html>
<ion-label><span core-mark-required="true"></code>

<code html>
<ion-avatar core-user-avatar …></code>
now needs to be:
<code html>
<core-user-avatar …></code>

==You can now use ES6==

In v3.9.5 we will increase the minimum Android version to use the app. The newer Cordova and Ionic versions only support Android 5.1+ with newer WebViews, so that will also be the requirement of the app.

The new app will require Android 5.1 with WebView 61+. This means that the Javascript for the app can now be developed in ES6 instead of ES5. Also, you can use arrow functions since they were introduced in WebView 55 and iOS 10.3.

This means that the app is no longer transpiled to ES5, and that can break your plugin’s Javascript if you’re extending a class. In Ionic 3, when your plugin receives a class it actually receives a function, and that affects the way to extend it. Now your plugin will receive a Javascript class.

E.g. to create a subclass of ''CoreContentLinksModuleIndexHandler'' you had to do:

<code javascript>
function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

// Rest of constructor.
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;</code>

Now it’s done like this:

<code javascript>
class AddonModChoiceGroupLinkHandler extends this.CoreContentLinksModuleIndexHandler {
constructor() {
super('AddonModChoiceGroup', 'choicegroup');

// Rest of constructor.
}
}</code>

==Changes in the app’s code==

We’ve also done some changes to the code of the app. Most of these changes probably won’t affect your plugin, but we still list them all just in case:

* ''<core-icon>'' is now deprecated, please use ''<ion-icon>'' instead. Right now you can use font-awesome icons with ion-icon. However, it still hasn’t been decided whether font awesome will be used in Moodle 4.0 or not, so it might happen that font-awesome is removed from the app in the future.
* To “cross out” an icon using ion-icon now you need to use ''class=”icon-slash”'' instead of ''slash=”true”''.
* The function ''syncOnSites'' from ''CoreSyncBaseProvider'' now expects to receive a function with the parameters already bound. That is, instead of:

<code javascript>
syncOnSites(‘events', this.syncAllEventsFunc.bind(this), [force], siteId);</code>

You should now do:

<code javascript>
syncOnSites(‘events', this.syncAllEventsFunc.bind(this, force), siteId);</code>

* All the delegates that previously supplied an injector parameter to its handlers now no longer do that. E.g. the function ''getComponent()'' in ''CoreUserProfileFieldDelegate'' used to receive an injector as a parameter, now it won’t receive any parameter.
* All the delegates that previously supplied a ''NavController'' parameter to its handlers now no longer do that. E.g. the function ''openCourse()'' in ''CoreCourseFormatDelegate'' will no longer receive the ''NavController'' parameter.
* The handlers registered in ''CoreCourseOptionsDelegate'' now need to return the properties page+pageParams instead of component+componentData. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
* The handlers registered in ''CoreUserDelegate'' have changed a bit. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
** Handlers can now define a ''cacheEnabled'' property (false by default) to cache ''isEnabledForUser'' calls.
** In the function ''isEnabledForUser'', the params ''navOptions'' and ''admOptions'' have been removed.
** ''isEnabledForUser'' is now optional and defaults to true.
** Now they can implement a new function ''isEnabledForCourse'', and this function will receive the ''navOptions'' and ''admOptions''. If not defined defaults to true.
* The function ''prefetchPackage'' in the ''CoreCourseActivityPrefetchHandlerBase'' has changed. If you were using this class to implement your own prefetch handler you might need to update its code.
* ''CoreInitDelegate'' has been deleted. Now the initialization of the app is done via Angular’s ''APP_INITIALIZER''. Please notice that ''APP_INITIALIZER'' cannot and shouldn’t be used by plugins.
* The function ''getAdditionalDownloadableFiles'' in question types now needs to return a list of ''CoreWSExternalFile'', it no longer accepts a list of strings.
* Files stored to be uploaded later using ''CoreFileUploaderProvider'' no longer have an “offline” property, now they’re just instances of ''FileEntry''.
* ''ionViewCanLeave'' function has been renamed to ''canLeave''.
* The ''onchange'' method of the ''Network'' service is now called ''onChange''.

==Is there any example I can look at?==

If you used the app’s code as an example to build your plugin you can do it again. Most of the templates in the app have already been adapted to Ionic 5. You can see the Ionic 5 code in this branch:

[https://github.com/moodlehq/moodleapp/tree/ionic5 App source code]

I also adapted the choicegroup plugin to make it work in ionic5, you can take a look too. This hasn’t been integrated into the plugin yet because I haven’t done thorough testing yet, you can find it here:

[https://github.com/dpalou/moodle-mod_choicegroup Choicegroup plugin]

Using the Moodle App in a browser

2020-12-09T14:50:00Z

Dpalou: /* Installation */

Chromium or Google Chrome browser are the recommended tools for Moodle Mobile development. But remember that if you are going to use functions provided by Phonegap you should use the Android SDK or iOs developer tools.
{{Moodle Mobile}}
{{Work in progress}}

== Differences between Chromium and Google Chrome ==

Google Chrome is the Chromium open source project built, packaged, and distributed by Google. We can say that Chromium is Google Chrome without the "Google" add-ons

See https://code.google.com/p/chromium/wiki/ChromiumBrowserVsGoogleChrome for more information

We recommend using Chromium instead Google Chrome

== Advantages and disadvantages of using Chromium/Google Chrome ==

Main advantages
* Quick development
* DOM inspector
* Network monitor
* Database (local storage) inspector
* Emulation options

Disadvantages
* You can't test/develop using Phonegap APIs and Plugins
* If you use custom Phonegap code (including plugins) you will need to edit the mm.cordova.js for "emulate" those APIs in a browser
* You will always need to test in a real device and emulator prior to a production release
* You will need to verify that your CSS/layout works the same in an Android/iOs device

== Installation ==

Install the “Chromium” browser just downloading it from https://download-chromium.appspot.com/

In order to be able to access any domain via AJAX from the local file:/// protocol, you must run Chromium or Google Chrome in Unsafe mode adding these parameters:

--allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

For more info about the user data dir, please see [https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md this documentation].

NOTE: Since Moodle 3.0 an onwards this shouldn't be necessary for WebService calls since the Web Service layer supports CORS requests, but it could still be needed to download some files.

IMPORTANT: I strongly recommend you create a new link or application launch called "Chrome Unsafe" and use it only for testing the app. Better if you only use this browser for development. In Linux and possibly other operating systems the below arguments only work if you don't already have the same browser running without the args. Hence if you use "google-chrome" as your normal browser then use "chromium-browser" for your cors free debugging and vice versa.

How to open the browser from the Command line:

"Path to chrome\chrome.exe" --allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

or in Mac (you can use Automator for creating an app bundle)

open -a "Google Chrome" --args --allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

or for Chromium

open -a /Applications/Chromium.app --args --allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

In Mac you can use Automator for creating a launching app.

In Windows you can follow [https://www.chromium.org/developers/how-tos/run-chromium-with-flags this guide] to launch Chrome with those flags without using the command line.

Now, you can open the application running:
ionic serve --browser chromium
it should open a new tab in the current Chromium instance with the app, (remember that you have to open first the Chromium so it's started with all the additional arguments).

If the ionic serve command open a new browser window, you should copy the URL and then paste it in the Chromium instance you opened using the command shell.

== Sites for testing ==

You can test the application using existing sites configured to have the Mobile services enabled.

Real test site: If you type "student" or "teacher" in the "Site URL" field and then tap on "Add site" the app will connect to https://school.moodledemo.net. This site is reset every hour so you may find unexpected behaviors

== Browser Settings ==
[[{{ns:file}}:moodlemobile_developer.png|thumb|300px]]
You should develop always with the "Developer tools" panel open, you can open that panel with F12 (cmd + alt + i in Mac) or "Developer tools" in the Tools menu.

[[{{ns:file}}:moodlemobile_options.png|left]] Once opened, click on the wheel top-right corner to see the General options, you must Disable the cache there (this setting will work only if you have the Developer tools panel open)

You can dock or undock into a separate window the developer panel using the "Dock" option just at the right of the settings wheel, you can move the developer panel to your right and resize the main browser window to emulate a Mobile device

== Inspecting and changing the DOM ==

Using the "Elements" option you can manipulate the DOM:

* Add/modify style to elements
* Delete elements
* Move elements
* Inject HTML code

You have complete information here: https://developer.chrome.com/devtools/index

And also a free interactive course here: https://www.codeschool.com/courses/discover-devtools

== Monitor XHR (ajax) requests ==
[[{{ns:file}}:moodlemobile_network.png|thumb|300px]]

With the network panel you can check and filter all the HTTP request send from the app to your Moodle server.

You can preserve the log in the navigation, filter by type of requests and also see complete information of all the requests made to the server where is hosted your Moodle installation.

You can also identify with resources takes long to load

== Console, log and errors ==
[[{{ns:file}}:moodlemobile_log.png|thumb|300px]]

The console panel is used for displaying the app log and errors, you can also configure Chrome for displaying there XHR requests

In order to view the app log, you need first to enable Logging in the app (Options / Developers / Enable logging)

You can use the console also for executing javascript commands, the console has access to the complete MM global object so you can call from there to core APIs functions of the app

== Browsing the data base ==
[[{{ns:file}}:moodlemobile_localstorage.png|thumb|300px]]

The Mobile app stores information in the local HTML5 IndexedDB

You can inspect the local database in the Resources tab.

== File system ==
[[{{ns:file}}:moodlemobile_filesystem.png|thumb|300px]]

The first time you open the browser with the special flags you will see a couple of warnings, one asking you to accept to store information.

You have to "Accept" that warning because it means that you will be able to emulate the device file system using the browser.

For example, you will be able to download files to the browser storage (like the user profiles images, any resource in the course, etc..)

You can browse the files stored in the application going to Settings > About and clicking the Filesystem root link.

== Emulating devices ==
[[{{ns:file}}:moodlemobile_emulation.png|thumb|300px]]

You can emulate mobile devices changing orientation, resolution, geo-location, touch events... It's not recommended to use de "Emulation Device" option because it just changes the user-agent and you could get some fails because of the jQuery Swipe library.

The best option to test with the browser is just rescaling the window to get a new viewport size or use the screen settings in the "Emulation" screen.

== See also ==

[https://developer.chrome.com/devtools/index Chrome Developer Tools help]

[[Category: Mobile]]

Using the Moodle App in a browser

2020-12-09T14:45:53Z

Dpalou:

Chromium or Google Chrome browser are the recommended tools for Moodle Mobile development. But remember that if you are going to use functions provided by Phonegap you should use the Android SDK or iOs developer tools.
{{Moodle Mobile}}
{{Work in progress}}

== Differences between Chromium and Google Chrome ==

Google Chrome is the Chromium open source project built, packaged, and distributed by Google. We can say that Chromium is Google Chrome without the "Google" add-ons

See https://code.google.com/p/chromium/wiki/ChromiumBrowserVsGoogleChrome for more information

We recommend using Chromium instead Google Chrome

== Advantages and disadvantages of using Chromium/Google Chrome ==

Main advantages
* Quick development
* DOM inspector
* Network monitor
* Database (local storage) inspector
* Emulation options

Disadvantages
* You can't test/develop using Phonegap APIs and Plugins
* If you use custom Phonegap code (including plugins) you will need to edit the mm.cordova.js for "emulate" those APIs in a browser
* You will always need to test in a real device and emulator prior to a production release
* You will need to verify that your CSS/layout works the same in an Android/iOs device

== Installation ==

Install the “Chromium” browser just downloading it from https://download-chromium.appspot.com/

In order to be able to access any domain via AJAX from the local file:/// protocol, you must run Chromium or Google Chrome in Unsafe mode adding these parameters:

--allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

For more info about the user data dir, please see [https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md this documentation].

NOTE: Since Moodle 3.0 an onwards this shouldn't be necessary for WebService calls since the Web Service layer supports CORS requests, but it could still be needed to download some files.

IMPORTANT: I strongly recommend you create a new link or application launch called "Chrome Unsafe" and use it only for testing the app. Better if you only use this browser for development. In Linux and possibly other operating systems the below arguments only work if you don't already have the same browser running without the args. Hence if you use "google-chrome" as your normal browser then use "chromium-browser" for your cors free debugging and vice versa.

How to open the browser:

"Path to chrome\chrome.exe" --allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

or in Mac (you can use Automator for creating an app bundle)

open -a "Google Chrome" --args --allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

or for Chromium

open -a /Applications/Chromium.app --args --allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

In Mac you can use Automator for creating a launching app

Now, you can open the application running:
ionic serve --browser chromium
it should open a new tab in the current Chromium instance with the app, (remember that you have to open first the Chromium so it's started with all the additional arguments).

If the ionic serve command open a new browser window, you should copy the URL and then paste it in the Chromium instance you opened using the command shell.

== Sites for testing ==

You can test the application using existing sites configured to have the Mobile services enabled.

Real test site: If you type "student" or "teacher" in the "Site URL" field and then tap on "Add site" the app will connect to https://school.moodledemo.net. This site is reset every hour so you may find unexpected behaviors

== Browser Settings ==
[[{{ns:file}}:moodlemobile_developer.png|thumb|300px]]
You should develop always with the "Developer tools" panel open, you can open that panel with F12 (cmd + alt + i in Mac) or "Developer tools" in the Tools menu.

[[{{ns:file}}:moodlemobile_options.png|left]] Once opened, click on the wheel top-right corner to see the General options, you must Disable the cache there (this setting will work only if you have the Developer tools panel open)

You can dock or undock into a separate window the developer panel using the "Dock" option just at the right of the settings wheel, you can move the developer panel to your right and resize the main browser window to emulate a Mobile device

== Inspecting and changing the DOM ==

Using the "Elements" option you can manipulate the DOM:

* Add/modify style to elements
* Delete elements
* Move elements
* Inject HTML code

You have complete information here: https://developer.chrome.com/devtools/index

And also a free interactive course here: https://www.codeschool.com/courses/discover-devtools

== Monitor XHR (ajax) requests ==
[[{{ns:file}}:moodlemobile_network.png|thumb|300px]]

With the network panel you can check and filter all the HTTP request send from the app to your Moodle server.

You can preserve the log in the navigation, filter by type of requests and also see complete information of all the requests made to the server where is hosted your Moodle installation.

You can also identify with resources takes long to load

== Console, log and errors ==
[[{{ns:file}}:moodlemobile_log.png|thumb|300px]]

The console panel is used for displaying the app log and errors, you can also configure Chrome for displaying there XHR requests

In order to view the app log, you need first to enable Logging in the app (Options / Developers / Enable logging)

You can use the console also for executing javascript commands, the console has access to the complete MM global object so you can call from there to core APIs functions of the app

== Browsing the data base ==
[[{{ns:file}}:moodlemobile_localstorage.png|thumb|300px]]

The Mobile app stores information in the local HTML5 IndexedDB

You can inspect the local database in the Resources tab.

== File system ==
[[{{ns:file}}:moodlemobile_filesystem.png|thumb|300px]]

The first time you open the browser with the special flags you will see a couple of warnings, one asking you to accept to store information.

You have to "Accept" that warning because it means that you will be able to emulate the device file system using the browser.

For example, you will be able to download files to the browser storage (like the user profiles images, any resource in the course, etc..)

You can browse the files stored in the application going to Settings > About and clicking the Filesystem root link.

== Emulating devices ==
[[{{ns:file}}:moodlemobile_emulation.png|thumb|300px]]

You can emulate mobile devices changing orientation, resolution, geo-location, touch events... It's not recommended to use de "Emulation Device" option because it just changes the user-agent and you could get some fails because of the jQuery Swipe library.

The best option to test with the browser is just rescaling the window to get a new viewport size or use the screen settings in the "Emulation" screen.

== See also ==

[https://developer.chrome.com/devtools/index Chrome Developer Tools help]

[[Category: Mobile]]

Contributing to the Moodle app

2020-08-07T08:50:08Z

Dpalou: /* Translation */

There are lots of ways you can contribute to the Moodle App project. If you want to see more ways to contribute to the Moodle project, please see [[Contributing_to_Moodle|Contributing to Moodle]].

==User support==

Join in with the forum discussions in [https://moodle.org/mod/forum/view.php?id=7798 Moodle for Mobile forum].

==Documentation==

Help write and edit our [https://docs.moodle.org/overview/ user documentation in various languages] or our [[Main_Page|developer docs]].

==Plugins==

Have you developed a Moodle plugin? You can [[Mobile_support_for_plugins|adapt your plugin to the Moodle App]].

==Development==

Fix a bug or add a new feature in the Moodle App. The development process is similar to the Moodle development process.

First you should [[Setting_up_your_development_environment_for_Moodle_Mobile_2|set up your development environment]]. Once your issue is ready you can use our [[Moodle_App_scripts:_gulp_push|gulp push script]] to easily add your changes to the Moodle Tracker.

==Translation==

Assist with the [[Translating_the_Moodle_app|translation of the Moodle App]].

Contributing to the Moodle app

2020-08-07T08:39:43Z

Dpalou: Created page with "There are lots of ways you can contribute to the Moodle App project. If you want to see more ways to contribute to the Moodle project, please see Contributing_to_Moodle|Cont..."

Moodle App Scripts: gulp push

2020-08-07T08:27:07Z

Dpalou:

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

== Overview ==

The ''gulp push'' command automatically pushes a branch to a git remote and then updates the corresponding Moodle Tracker (Jira) issue with the diff URL or a patch file, similar to ''mdk push -t''. This script was developed using [https://github.com/FMCorz/mdk mdk] as an example. It's meant to be used for MOBILE issues, so it will only update the "master" fields in the tracker.

Please notice you need to have the Moodle App 3.9.3 code to be able to run this command. To run it, just go to the root of the project and run:

<code php>gulp push</code>

By default, running ''gulp push'' without any parameter will push the '''current branch''' to the '''origin''' remote. Then it will guess the issue number based on the branch name and it will update the tracker issue to include the following fields:

* If it's a security issue, it will upload a patch file.
* Otherwise it will update the fields: "Pull from Repository", "Pull Master Branch", "Pull Master Diff URL".

== Parameters ==

All the parameters must be passed preceded by "--". Example:

<code php>gulp push --branch MOBILE-1234 --remote upstream --force</code>

* branch: To specify the branch you want to push. By default: current branch.
* remote: To specify the remote where you want to push your branch. By default: origin.
* force: To force the push of changes to the git remote. By default: false.
* patch: To upload a patch file instead of a diff URL. If the issue you're pushing is a security issue, this setting will be forced to true. By default: false.

== Moodle Tracker data ==

The script needs the following data to be able to update the tracker: tracker URL, username and password.

First the script will try to read the URL and password from the [[Moodle_App_scripts:_gulp_push#Config_file|config file]]. If the file doesn't exist or it lacks any of those fields, it will check if ''mdk'' is installed and configured. If it is, then the script will use the same tracker URL and username as ''mdk''.

If none of those conditions are fulfilled, then the script will ask the user to input the URL and username and it will store them in the config file.

We use the [https://github.com/atom/node-keytar node-keytar] library to manage the password. This library uses Keychain on macOS, Secret Service API/libsecret on Linux, and Credential Vault on Windows. We use the same key as ''mdk'' to store and retrieve the tracker password, so if you already use ''mdk'' this script will automatically get the password (it will probably ask your root/admin password in the device to be able to access it).

== Config file ==

The script will use a file named ''.moodleapp-dev-config'' to store some configuration data '''in JSON format'''. You can also create or edit that file to configure the script's behaviour. These are the fields it accepts:

* upstreamRemote: The upstream where to push the branch if the remote param isn't supplied. By default: origin.
* tracker.url: URL of the tracker to update. By default: https://tracker.moodle.org/.
* tracker.username: Username to use in the tracker.
* tracker.fieldnames.repositoryurl: Name of the tracker field where to put the repository URL. By default: "Pull from Repository".
* tracker.fieldnames.branch: Name of the tracker field where to put the branch name. By default: "Pull Master Branch".
* tracker.fieldnames.diffurl: Name of the tracker field where to put the diff URL. By default: "Pull Master Diff URL".
* wording.branchRegex: Regex to use to identify the issue number based on the branch name. By default: "(MOBILE)[-_]([0-9]+)". If you want to use the script to handle issues that aren't MOBILE you'll need to update this field. E.g. if you work on 2 projects: "(MOBILE|MYPROJECT)[-_]([0-9]+)"
* {PROJECTNAME}.repositoryUrl: To specify the git URL where to push changes for a certain project ({PROJECTNAME} is the name of the project). This can be used if you work on different projects and you want to push changes to different remotes depending on the project. E.g.: ''MOBILE.repositoryUrl: https://github.com/moodlehq/moodleapp''
* {PROJECTNAME}.diffUrlTemplate: To specify the diff URL template to use for a certain project ({PROJECTNAME} is the name of the project). By default: remoteUrl + '/compare/%headcommit%...%branch%'.

Setting up your development environment for the Moodle App

2020-08-07T08:23:20Z

Dpalou: /* Linux only: libsecret */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.9.x version of the Moodle Mobile app.

== Overview ==

The structure of this page is
* the first part, up to the point where you get the <tt>npm start</tt> command to work is what you need to be able to do development on the app and test it in a browser.
* the second part is about how to build a version of the app that can be run on a device.
* then at the end is a list of troubleshooting advice. If you encounter a problem that is not already listed, please consider adding it.

The majority of your development will be done using a browser. You will probably only begin to use an emulator once you need to simulate a real mobile device.

If you are just [[Mobile support for plugins|adding mobile support to plugins]], remember that most of your development can be done using the online pre-built version at https://mobileapp.moodledemo.net/ (with Chrome or Chromium). However, if you want to be able to to write [[Acceptance_testing_for_the_mobile_app|automated acceptance tests for the app]] then you need to follow this page at least as far as getting the <tt>npm start</tt> command to work on this page.

== Requirements ==

Windows tip: ingore any use of the sudo command below. Just use the command without it. Most things work that way. And if they don't, try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the installation a bit easier than the official installation route.

nvm install node
nvm use 11 # This is important, npm commands will not work in other versions

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same nvm commands as for Linux.

On Mac we recommend installing NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it is more tricky to get that to work. If you have previously installed Node directly, and want to switch to nvm, you need to uninstall node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Windows only: Native build dependencies===

node-gyp requires native build tools for your platform. If you're developing on Mac or Linux, you'll probably have these already ([https://github.com/nodejs/node-gyp/blob/master/README.md refer to the docs if you don't]). On Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

Warning! this installer can take a very, very long time to run. We were seeing it take hours. Literally. Be prepared to be very patient. Don't just make the natural assumption that it has crashed.

===Mac only: Push notifications===

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the '''Moodle.xcworkspace''' file, more information here: MOBILE-1970

===Linux only: libsecret===

In Moodle App 3.9.3 we'll include a new script to easily push diff URLs to Moodle Tracker (Jira): [[Moodle App scripts: gulp push|gulp push]]. One of the libraries used requires the libsecret library to be installed in Linux before running ''npm install''. Depending on your distribution, you will need to run the following command:

Debian/Ubuntu: sudo apt-get install libsecret-1-dev

Red Hat-based: sudo yum install libsecret-devel

Arch Linux: sudo pacman -S libsecret

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be a good idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodleapp.git moodleapp
cd moodleapp
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && npx cordova prepare && npx gulp</tt> (installing npm dependencies, preparing cordova and running default gulp tasks). That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>npm start</tt> (see below) may work, even if <tt>npx cordova prepare</tt> gives errors. You only really need <tt>npx cordova prepare</tt> to work if you are going to go on and build the app for a mobile device or emulator.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

Then, start the Ionic server:

npm start

Congratulations! Now that you have got to the point where the <tt>npm start</tt> command works, you can start doing development on the app. You only need to read the rest of the page if you want to build packaged versions of the app.

== Updating ionic and cordova ==

Update project platforms:

npx ionic cordova platform remove android
npx ionic cordova platform remove ios
npx ionic cordova platform add android
npx ionic cordova platform add ios

== Updating plugins ==

npx cordova plugin remove your_plugin_id
npx cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

For convenience, you can use the following commands:

npm run dev:android
npm run dev:ios
npm run prod:android # Uses aot compilation, read below
npm run prod:ios # Uses aot compilation, read below

If the build fails, please run <code>npx cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: <tt>gradle</tt> and <tt>libgradle-android-plugin-java</tt> (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running <tt>npm start</tt> or <tt>npx ionic build</tt> compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''npx cordova run android''" or "''npx cordova build ios''" (please don't use "''npx ionic cordova ...''" nor "''npm start''" because it will override your build files!).

== Troubleshooting ==

=== Strange NPM errors ===

To get more debug output from npm commands, see https://docs.npmjs.com/misc/config#shorthands-and-other-cli-niceties. In particular try adding <tt>--loglevel verbose</tt> (or <tt>--loglevel info</tt> or <tt>--loglevel silly</tt>) to the command-line.

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Sometimes running the following command will fix the problem:

npm rebuild node-sass

If the issue persists, please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== Could not resolve all dependencies for configuration ':_debugCompile'. ===
Open the Android SDK Manager and make sure you have installed: Android Support Repository, Android Support Library, Google Play Services and Google Repository.

=== Could not find com.android.support:support-v4:XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> and retry.

=== ReferenceError: internalBinding is not defined ===

This [https://stackoverflow.com/questions/53146394/node-app-fails-to-run-on-mojave-referenceerror-internalbinding-is-not-defined seems to be] an error with 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

│ npm update check failed │
│ Try running with sudo or get access │
│ to the local update config store via │
│ sudo chown -R $USER:$(id -gn $USER) C:\Users\username\.config │

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

===Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ...===

You need to heed the advice at https://www.npmjs.com/package/npm#installing-on-cygwin. Cygwin users are not welcome in the Node world. However, you just need to ensure that Msysgit is on your windows path and that the cygwin bin folder is not. Then always use another shell like Powershell for your Moodle mobile development. (You don't need your Cygwin bin folder on the Windows path. It automatically gets added to the path when you lauch Cygwin bash.)

===The product name change (<name> tag) in config.xml is not supported dynamically===

According to Google, this happens when you create the iOS platform with a certain <name> and then you change that name in config.xml. It's weird that the installation process does that, it should create the platform with the right name unless it was changed manually.

The solution seems to be removing and adding the iOS platform again:

npx ionic platform remove ios
npx ionic platform add ios

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

===Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0".===

The ''cordova-plugin-file'' version specified in config.xml is 6.0.1, for some reason the installation process installed a wrong version for that plugin. You can manually install the ''cordova-plugin-file'' plugin like this:

npx cordova plugin remove cordova-plugin-file
npx cordova plugin add cordova-plugin-file@6.0.1

Please notice that if there is any plugin installed that depends on ''cordova-plugin-file'' you'll have to remove and re-add them too.

Note that this does not seem to prevent <tt>npm start</tt> from serving a working app if you run <tt>npx gulp</tt> after <tt>npm run setup</tt> has failed with this error.

===Mac: linker code failed with exit code 1===
If you get this error when trying to build the Moodle app with XCode, some dependencies might not have installed correctly.

Ensure you have followed the [https://docs.moodle.org/dev/Setting_up_your_development_environment_for_Moodle_Mobile_2#Mac_only:_Push_notifications| Mac only: Push notifications] steps above (particularly opening the .xcworkspace file rather than the .xcodeproj file). Then run the following:

npm run setup
cd platforms/ios
pod install

Now try running the build again in XCode.

===Windows: <code>npm start</code> hangs after "Starting 'watch'"===
This appears to have happened since the move to npx. Try running the npx commands generated by npm run directly in bash:
npx gulp watch & npx ionic-app-scripts serve -b --devapp --address=0.0.0.0

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2020-08-07T07:16:40Z

Dpalou: /* Requirements */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.9.x version of the Moodle Mobile app.

== Overview ==

The structure of this page is
* the first part, up to the point where you get the <tt>npm start</tt> command to work is what you need to be able to do development on the app and test it in a browser.
* the second part is about how to build a version of the app that can be run on a device.
* then at the end is a list of troubleshooting advice. If you encounter a problem that is not already listed, please consider adding it.

The majority of your development will be done using a browser. You will probably only begin to use an emulator once you need to simulate a real mobile device.

If you are just [[Mobile support for plugins|adding mobile support to plugins]], remember that most of your development can be done using the online pre-built version at https://mobileapp.moodledemo.net/ (with Chrome or Chromium). However, if you want to be able to to write [[Acceptance_testing_for_the_mobile_app|automated acceptance tests for the app]] then you need to follow this page at least as far as getting the <tt>npm start</tt> command to work on this page.

== Requirements ==

Windows tip: ingore any use of the sudo command below. Just use the command without it. Most things work that way. And if they don't, try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the installation a bit easier than the official installation route.

nvm install node
nvm use 11 # This is important, npm commands will not work in other versions

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same nvm commands as for Linux.

On Mac we recommend installing NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it is more tricky to get that to work. If you have previously installed Node directly, and want to switch to nvm, you need to uninstall node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Windows only: Native build dependencies===

node-gyp requires native build tools for your platform. If you're developing on Mac or Linux, you'll probably have these already ([https://github.com/nodejs/node-gyp/blob/master/README.md refer to the docs if you don't]). On Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

Warning! this installer can take a very, very long time to run. We were seeing it take hours. Literally. Be prepared to be very patient. Don't just make the natural assumption that it has crashed.

===Mac only: Push notifications===

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the '''Moodle.xcworkspace''' file, more information here: MOBILE-1970

===Linux only: libsecret===

In Moodle App 3.9.3 we'll include a new script to easily push diff URLs to Jira: [[Moodle App scripts: gulp push|gulp push]]. One of the libraries used requires the libsecret library to be installed in Linux before running ''npm install''. Depending on your distribution, you will need to run the following command:

Debian/Ubuntu: sudo apt-get install libsecret-1-dev

Red Hat-based: sudo yum install libsecret-devel

Arch Linux: sudo pacman -S libsecret

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be a good idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodleapp.git moodleapp
cd moodleapp
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && npx cordova prepare && npx gulp</tt> (installing npm dependencies, preparing cordova and running default gulp tasks). That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>npm start</tt> (see below) may work, even if <tt>npx cordova prepare</tt> gives errors. You only really need <tt>npx cordova prepare</tt> to work if you are going to go on and build the app for a mobile device or emulator.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

Then, start the Ionic server:

npm start

Congratulations! Now that you have got to the point where the <tt>npm start</tt> command works, you can start doing development on the app. You only need to read the rest of the page if you want to build packaged versions of the app.

== Updating ionic and cordova ==

Update project platforms:

npx ionic cordova platform remove android
npx ionic cordova platform remove ios
npx ionic cordova platform add android
npx ionic cordova platform add ios

== Updating plugins ==

npx cordova plugin remove your_plugin_id
npx cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

For convenience, you can use the following commands:

npm run dev:android
npm run dev:ios
npm run prod:android # Uses aot compilation, read below
npm run prod:ios # Uses aot compilation, read below

If the build fails, please run <code>npx cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: <tt>gradle</tt> and <tt>libgradle-android-plugin-java</tt> (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running <tt>npm start</tt> or <tt>npx ionic build</tt> compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''npx cordova run android''" or "''npx cordova build ios''" (please don't use "''npx ionic cordova ...''" nor "''npm start''" because it will override your build files!).

== Troubleshooting ==

=== Strange NPM errors ===

To get more debug output from npm commands, see https://docs.npmjs.com/misc/config#shorthands-and-other-cli-niceties. In particular try adding <tt>--loglevel verbose</tt> (or <tt>--loglevel info</tt> or <tt>--loglevel silly</tt>) to the command-line.

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Sometimes running the following command will fix the problem:

npm rebuild node-sass

If the issue persists, please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== Could not resolve all dependencies for configuration ':_debugCompile'. ===
Open the Android SDK Manager and make sure you have installed: Android Support Repository, Android Support Library, Google Play Services and Google Repository.

=== Could not find com.android.support:support-v4:XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> and retry.

=== ReferenceError: internalBinding is not defined ===

This [https://stackoverflow.com/questions/53146394/node-app-fails-to-run-on-mojave-referenceerror-internalbinding-is-not-defined seems to be] an error with 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

│ npm update check failed │
│ Try running with sudo or get access │
│ to the local update config store via │
│ sudo chown -R $USER:$(id -gn $USER) C:\Users\username\.config │

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

===Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ...===

You need to heed the advice at https://www.npmjs.com/package/npm#installing-on-cygwin. Cygwin users are not welcome in the Node world. However, you just need to ensure that Msysgit is on your windows path and that the cygwin bin folder is not. Then always use another shell like Powershell for your Moodle mobile development. (You don't need your Cygwin bin folder on the Windows path. It automatically gets added to the path when you lauch Cygwin bash.)

===The product name change (<name> tag) in config.xml is not supported dynamically===

According to Google, this happens when you create the iOS platform with a certain <name> and then you change that name in config.xml. It's weird that the installation process does that, it should create the platform with the right name unless it was changed manually.

The solution seems to be removing and adding the iOS platform again:

npx ionic platform remove ios
npx ionic platform add ios

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

===Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0".===

The ''cordova-plugin-file'' version specified in config.xml is 6.0.1, for some reason the installation process installed a wrong version for that plugin. You can manually install the ''cordova-plugin-file'' plugin like this:

npx cordova plugin remove cordova-plugin-file
npx cordova plugin add cordova-plugin-file@6.0.1

Please notice that if there is any plugin installed that depends on ''cordova-plugin-file'' you'll have to remove and re-add them too.

Note that this does not seem to prevent <tt>npm start</tt> from serving a working app if you run <tt>npx gulp</tt> after <tt>npm run setup</tt> has failed with this error.

===Mac: linker code failed with exit code 1===
If you get this error when trying to build the Moodle app with XCode, some dependencies might not have installed correctly.

Ensure you have followed the [https://docs.moodle.org/dev/Setting_up_your_development_environment_for_Moodle_Mobile_2#Mac_only:_Push_notifications| Mac only: Push notifications] steps above (particularly opening the .xcworkspace file rather than the .xcodeproj file). Then run the following:

npm run setup
cd platforms/ios
pod install

Now try running the build again in XCode.

===Windows: <code>npm start</code> hangs after "Starting 'watch'"===
This appears to have happened since the move to npx. Try running the npx commands generated by npm run directly in bash:
npx gulp watch & npx ionic-app-scripts serve -b --devapp --address=0.0.0.0

== See also ==

http://ionicframework.com/docs/cli/

Moodle App Scripts: gulp push

2020-08-07T07:14:45Z

Dpalou:

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

== Overview ==

The ''gulp push'' command automatically pushes a branch to a git remote and then updates the corresponding tracker issue with the diff URL or a patch file, similar to ''mdk push -t''. This script was developed using [https://github.com/FMCorz/mdk mdk] as an example. It's meant to be used for MOBILE issues, so it will only update the "master" fields in the tracker.

Please notice you need to have the Moodle App 3.9.3 code to be able to run this command. To run it, just go to the root of the project and run:

<code php>gulp push</code>

By default, running ''gulp push'' without any parameter will push the '''current branch''' to the '''origin''' remote. Then it will guess the issue number based on the branch name and it will update the Jira issue to include the following fields:

* If it's a security issue, it will upload a patch file.
* Otherwise it will update the fields: "Pull from Repository", "Pull Master Branch", "Pull Master Diff URL".

== Parameters ==

All the parameters must be passed preceded by "--". Example:

<code php>gulp push --branch MOBILE-1234 --remote upstream --force</code>

* branch: To specify the branch you want to push. By default: current branch.
* remote: To specify the remote where you want to push your branch. By default: origin.
* force: To force the push of changes to the git remote. By default: false.
* patch: To upload a patch file instead of a diff URL. If the issue you're pushing is a security issue, this setting will be forced to true. By default: false.

== Tracker data ==

The script needs the following data to be able to update the tracker: tracker URL, username and password.

First the script will try to read the URL and password from the [[Moodle_App_scripts:_gulp_push#Config_file|config file]]. If the file doesn't exist or it lacks any of those fields, it will check if ''mdk'' is installed and configured. If it is, then the script will use the same tracker URL and username as ''mdk''.

If none of those conditions are fulfilled, then the script will ask the user to input the URL and username and it will store them in the config file.

We use the [https://github.com/atom/node-keytar node-keytar] library to manage the password. This library uses Keychain on macOS, Secret Service API/libsecret on Linux, and Credential Vault on Windows. We use the same key as ''mdk'' to store and retrieve the Jira password, so if you already use ''mdk'' this script will automatically get the password (it will probably ask your root/admin password in the device to be able to access it).

== Config file ==

The script will use a file named ''.moodleapp-dev-config'' to store some configuration data '''in JSON format'''. You can also create or edit that file to configure the script's behaviour. These are the fields it accepts:

* upstreamRemote: The upstream where to push the branch if the remote param isn't supplied. By default: origin.
* tracker.url: URL of the tracker to update. By default: https://tracker.moodle.org/.
* tracker.username: Username to use in the tracker.
* tracker.fieldnames.repositoryurl: Name of the tracker field where to put the repository URL. By default: "Pull from Repository".
* tracker.fieldnames.branch: Name of the tracker field where to put the branch name. By default: "Pull Master Branch".
* tracker.fieldnames.diffurl: Name of the tracker field where to put the diff URL. By default: "Pull Master Diff URL".
* wording.branchRegex: Regex to use to identify the issue number based on the branch name. By default: "(MOBILE)[-_]([0-9]+)". If you want to use the script to handle issues that aren't MOBILE you'll need to update this field. E.g. if you work on 2 projects: "(MOBILE|MYPROJECT)[-_]([0-9]+)"
* {PROJECTNAME}.repositoryUrl: To specify the git URL where to push changes for a certain project ({PROJECTNAME} is the name of the project). This can be used if you work on different projects and you want to push changes to different remotes depending on the project. E.g.: ''MOBILE.repositoryUrl: https://github.com/moodlehq/moodleapp''
* {PROJECTNAME}.diffUrlTemplate: To specify the diff URL template to use for a certain project ({PROJECTNAME} is the name of the project). By default: remoteUrl + '/compare/%headcommit%...%branch%'.

Moodle App Scripts: gulp push

2020-08-07T07:13:57Z

Dpalou: Created page with "{{Moodle Mobile}} {{Moodle Mobile 3.9.3}} == Overview == The ''gulp push'' command automatically pushes a branch to a git remote and then updates the corresponding tracker i..."

{{Moodle Mobile}}
{{Moodle Mobile 3.9.3}}

== Overview ==

The ''gulp push'' command automatically pushes a branch to a git remote and then updates the corresponding tracker issue with the diff URL or a patch file, similar to ''mdk push -t''. This script was developed using [https://github.com/FMCorz/mdk mdk] as an example. It's meant to be used for MOBILE issues, so it will only update the "master" fields in the tracker.

Please notice you need to have the Moodle App 3.9.3 code to be able to run this command. To run it, just go to the root of the project and run:

<code php>gulp push</code>

By default, running ''gulp push'' without any parameter will push the '''current branch''' to the '''origin''' remote. Then it will guess the issue number based on the branch name and it will update the Jira issue to include the following fields:

* If it's a security issue, it will upload a patch file.
* Otherwise it will update the fields: "Pull from Repository", "Pull Master Branch", "Pull Master Diff URL".

== Parameters ==

All the parameters must be passed preceded by "--". Example:

<code php>gulp push --branch MOBILE-1234 --remote upstream --force</code>

* branch: To specify the branch you want to push. By default: current branch.
* remote: To specify the remote where you want to push your branch. By default: origin.
* force: To force the push of changes to the git remote. By default: false.
* patch: To upload a patch file instead of a diff URL. If the issue you're pushing is a security issue, this setting will be forced to true. By default: false.

== Tracker data ==

The script needs the following data to be able to update the tracker: tracker URL, username and password.

First the script will try to read the URL and password from the [[Moodle_App_scripts:_gulp_push#Config_file|config file]]. If the file doesn't exist or it lacks any of those fields, it will check if ''mdk'' is installed and configured. If it is, then the script will use the same tracker URL and username as ''mdk''.

If none of those conditions are fulfilled, then the script will ask the user to input the URL and username and it will store them in the config file.

We use the [https://github.com/atom/node-keytar node-keytar] library to manage the password. This library uses Keychain on macOS, Secret Service API/libsecret on Linux, and Credential Vault on Windows. We use the same key as ''mdk'' to store and retrieve the Jira password, so if you already use ''mdk'' this script will automatically get the password (it will probably ask your root/admin password in the device to be able to access it).

== Config file ==

The script will use a file named ''.moodleapp-dev-config'' to store some configuration data '''in JSON format'''. You can also create or edit that file to configure the script's behaviour. These are the fields it accepts:

* upstreamRemote: The upstream where to push the branch if the remote param isn't supplied. By default: origin.
* tracker.url: URL of the tracker to update. By default: https://tracker.moodle.org/.
* tracker.username: Username to use in the tracker.
* tracker.fieldnames.repositoryurl: Name of the tracker field where to put the repository URL. By default: "Pull from Repository".
* tracker.fieldnames.branch: Name of the tracker field where to put the branch name. By default: "Pull Master Branch".
* tracker.fieldnames.diffurl: Name of the tracker field where to put the diff URL. By default: "Pull Master Diff URL".
* wording.branchRegex: Regex to use to identify the issue number based on the branch name. By default: "(MOBILE)[-_]([0-9]+)". If you want to use the script to handle issues that aren't MOBILE you'll need to update this field. E.g. if you work on 2 projects: "(MOBILE|MYPROJECT)[-_]([0-9]+)"
* {PROJECTNAME}.repositoryUrl: To specify the git URL where to push changes for a certain project ({PROJECTNAME} is the name of the project). This can be used if you work on different projects and you want to push changes to different remotes depending on the project. E.g.: ''MOBILE.repositoryUrl: https://github.com/moodlehq/moodleapp''
* {PROJECTNAME}.diffUrlTemplate: To specify the diff URL template to use for a certain project ({PROJECTNAME} is the name of the project). By default: remoteUrl + '/compare/%headcommit%...%branch%'.

Moodle App Plugins Development Guide

2020-06-26T08:44:02Z

Dpalou: /* Options only for CoreBlockDelegate */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.
* '''ismenuhandler''': (optional) Supported from the 3.7.1 version of the app. Set it to true if you want your plugin to be displayed in the contextual menu of the course instead of in the top tabs. The contextual menu is displayed when you click in the 3-dots button at the top right of the course.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''method''' (optional): The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;
* '''coursepagemethod''': (optional) Supported from the 3.8 version of the app. If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML.

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.
* '''fallback''': (optional) Supported from the 3.9.0 version of the app. This option allows you to specify a block to use in the app instead of your block. E.g. you can make the app display the "My overview" block instead of your block in the app by setting: 'fallback' => 'myoverview'. The fallback will only be used if you don't specify a ''method'' and the ''type'' is different than ''title'' or ''prerendered''..

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate
* CoreFilterDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return this in the init method (only for Moodle 3.8 and onwards).

<code php>
return [
'disabled' => true
];</code>

If the Moodle version is older than 3.8, then the init method should return this:

<code php>
return [
'javascript' => 'this.HANDLER_DISABLED'
];</code>

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result;
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

===Implement a module similar to mod_label===

In Moodle 3.8 or higher, if your plugin doesn't support ''FEATURE_NO_VIEW_LINK'' and you don't specify a ''coursepagemethod'' then the module will only display the module description in the course page and it won't be clickable in the app, just like mod_label. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in ''displaydata'').

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the property ''coursepagemethod'' in the mobile.php. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only default HTML.

If you don't want your module to be clickable then you just need to remove the ''method'' from mobile.php. With these 2 changes you can have a module that behaves like mod_label in the app.

===Use Ionic navigation lifecycle functions===

Ionic let pages define some functions that will be called when certain navigation lifecycle events happen. For more info about these functions, see [https://ionicframework.com/blog/navigating-lifecycle-events/ this page].

You can define these functions in your plugin javascript:

<code javascript>
this.ionViewCanLeave = function() {
...
};</code>

So for example you can make your plugin ask for confirmation if the user tries to leave the page when he has some unsaved data.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]

Using the Moodle App in a browser

2020-04-01T08:18:17Z

Dpalou: /* Installation */

Chromium or Google Chrome browser are the recommended tools for Moodle Mobile development. But remember that if you are going to use functions provided by Phonegap you should use the Android SDK or iOs developer tools.
{{Moodle Mobile}}
{{Work in progress}}

== Differences between Chromium and Google Chrome ==

Google Chrome is the Chromium open source project built, packaged, and distributed by Google. We can say that Chromium is Google Chrome without the "Google" add-ons

See https://code.google.com/p/chromium/wiki/ChromiumBrowserVsGoogleChrome for more information

We recommend using Chromium instead Google Chrome

== Advantages and disadvantages of using Chromium/Google Chrome ==

Main advantages
* Quick development
* DOM inspector
* Network monitor
* Database (local storage) inspector
* Emulation options

Disadvantages
* You can't test/develop using Phonegap APIs and Plugins
* If you use custom Phonegap code (including plugins) you will need to edit the mm.cordova.js for "emulate" those APIs in a browser
* You will always need to test in a real device and emulator prior to a production release
* You will need to verify that your CSS/layout works the same in an Android/iOs device

== Installation ==

Install the “Chromium” browser just downloading it from https://download-chromium.appspot.com/

In order to be able to access any domain via AJAX from the local file:/// protocol, you must run Chromium or Google Chrome in Unsafe mode adding this param:

--allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

NOTE: Since Moodle 3.0 an onwards this shouldn't be necessary since the Web Service layer supports CORS requests apart from download assets such as your branded css.

IMPORTANT: I strongly recommend you create a new link or application launch called "Chrome Unsafe" and use it only for testing the app. Better if you only use this browser for development. In Linux and possibly other operating systems the below arguments only work if you don't already have the same browser running without the args. Hence if you use "google-chrome" as your normal browser then use "chromium-browser" for your cors free debugging and vice versa.

How to open the browser:

"Path to chrome\chrome.exe" --allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

or in Mac (you can use Automator for creating an app bundle)

open -a "Google Chrome" --args --allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

or for Chromium

open -a /Applications/Chromium.app --args --allow-file-access-from-files --disable-web-security --allow-running-insecure-content --no-referrers --unlimited-storage --auto-open-devtools-for-tabs --user-data-dir=PATH_TO_DATA_DIR

In Mac you can use Automator for creating a launching app

Now, you can open the application running:
ionic serve --browser chromium
it should open a new tab in the current Chromium instance with the app, (remember that you have to open first the Chromium so it's started with all the additional arguments).

If the ionic serve command open a new browser window, you should copy the URL and then paste it in the Chromium instance you opened using the command shell.

== Sites for testing ==

You can test the application using existing sites configured to have the Mobile services enabled.

Real test site: If you type "student" or "teacher" in the "Site URL" field and then tap on "Add site" the app will connect to http://school.demo.moodle.net. This site is reset every hour so you may find unexpected behaviors

== Browser Settings ==
[[{{ns:file}}:moodlemobile_developer.png|thumb|300px]]
You should develop always with the "Developer tools" panel open, you can open that panel with F12 (cmd + alt + i in Mac) or "Developer tools" in the Tools menu.

[[{{ns:file}}:moodlemobile_options.png|left]] Once opened, click on the wheel top-right corner to see the General options, you must Disable the cache there (this setting will work only if you have the Developer tools panel open)

You can dock or undock into a separate window the developer panel using the "Dock" option just at the right of the settings wheel, you can move the developer panel to your right and resize the main browser window to emulate a Mobile device

== Inspecting and changing the DOM ==

Using the "Elements" option you can manipulate the DOM:

* Add/modify style to elements
* Delete elements
* Move elements
* Inject HTML code

You have complete information here: https://developer.chrome.com/devtools/index

And also a free interactive course here: https://www.codeschool.com/courses/discover-devtools

== Monitor XHR (ajax) requests ==
[[{{ns:file}}:moodlemobile_network.png|thumb|300px]]

With the network panel you can check and filter all the HTTP request send from the app to your Moodle server.

You can preserve the log in the navigation, filter by type of requests and also see complete information of all the requests made to the server where is hosted your Moodle installation.

You can also identify with resources takes long to load

== Console, log and errors ==
[[{{ns:file}}:moodlemobile_log.png|thumb|300px]]

The console panel is used for displaying the app log and errors, you can also configure Chrome for displaying there XHR requests

In order to view the app log, you need first to enable Logging in the app (Options / Developers / Enable logging)

You can use the console also for executing javascript commands, the console has access to the complete MM global object so you can call from there to core APIs functions of the app

== Browsing the data base ==
[[{{ns:file}}:moodlemobile_localstorage.png|thumb|300px]]

The Mobile app stores information in the local HTML5 IndexedDB

You can inspect the local database in the Resources tab.

== File system ==
[[{{ns:file}}:moodlemobile_filesystem.png|thumb|300px]]

The first time you open the browser with the special flags you will see a couple of warnings, one asking you to accept to store information.

You have to "Accept" that warning because it means that you will be able to emulate the device file system using the browser.

For example, you will be able to download files to the browser storage (like the user profiles images, any resource in the course, etc..)

You can browse the files stored in the application going to Settings > About and clicking the Filesystem root link.

== Emulating devices ==
[[{{ns:file}}:moodlemobile_emulation.png|thumb|300px]]

You can emulate mobile devices changing orientation, resolution, geo-location, touch events... It's not recommended to use de "Emulation Device" option because it just changes the user-agent and you could get some fails because of the jQuery Swipe library.

The best option to test with the browser is just rescaling the window to get a new viewport size or use the screen settings in the "Emulation" screen.

== See also ==

[https://developer.chrome.com/devtools/index Chrome Developer Tools help]

[[Category: Mobile]]

Moodle App Plugins Development Guide

2019-12-20T15:16:47Z

Dpalou: /* Pure Javascript plugins */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.
* '''ismenuhandler''': (optional) Supported from the 3.7.1 version of the app. Set it to true if you want your plugin to be displayed in the contextual menu of the course instead of in the top tabs. The contextual menu is displayed when you click in the 3-dots button at the top right of the course.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''method''' (optional): The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;
* '''coursepagemethod''': (optional) Supported from the 3.8 version of the app. If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML.

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate
* CoreFilterDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return this in the init method (only for Moodle 3.8 and onwards).

<code php>
return [
'disabled' => true
];</code>

If the Moodle version is older than 3.8, then the init method should return this:

<code php>
return [
'javascript' => 'this.HANDLER_DISABLED'
];</code>

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

===Implement a module similar to mod_label===

In Moodle 3.8 or higher, if your plugin doesn't support ''FEATURE_NO_VIEW_LINK'' and you don't specify a ''coursepagemethod'' then the module will only display the module description in the course page and it won't be clickable in the app, just like mod_label. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in ''displaydata'').

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the property ''coursepagemethod'' in the mobile.php. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only default HTML.

If you don't want your module to be clickable then you just need to remove the ''method'' from mobile.php. With these 2 changes you can have a module that behaves like mod_label in the app.

===Use Ionic navigation lifecycle functions===

Ionic let pages define some functions that will be called when certain navigation lifecycle events happen. For more info about these functions, see [https://ionicframework.com/blog/navigating-lifecycle-events/ this page].

You can define these functions in your plugin javascript:

<code javascript>
this.ionViewCanLeave = function() {
...
};</code>

So for example you can make your plugin ask for confirmation if the user tries to leave the page when he has some unsaved data.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]

Moodle App Plugins Development Guide

2019-12-20T15:06:25Z

Dpalou: /* Advanced features */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.
* '''ismenuhandler''': (optional) Supported from the 3.7.1 version of the app. Set it to true if you want your plugin to be displayed in the contextual menu of the course instead of in the top tabs. The contextual menu is displayed when you click in the 3-dots button at the top right of the course.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''method''' (optional): The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;
* '''coursepagemethod''': (optional) Supported from the 3.8 version of the app. If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML.

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return this in the init method (only for Moodle 3.8 and onwards).

<code php>
return [
'disabled' => true
];</code>

If the Moodle version is older than 3.8, then the init method should return this:

<code php>
return [
'javascript' => 'this.HANDLER_DISABLED'
];</code>

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

===Implement a module similar to mod_label===

In Moodle 3.8 or higher, if your plugin doesn't support ''FEATURE_NO_VIEW_LINK'' and you don't specify a ''coursepagemethod'' then the module will only display the module description in the course page and it won't be clickable in the app, just like mod_label. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in ''displaydata'').

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the property ''coursepagemethod'' in the mobile.php. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only default HTML.

If you don't want your module to be clickable then you just need to remove the ''method'' from mobile.php. With these 2 changes you can have a module that behaves like mod_label in the app.

===Use Ionic navigation lifecycle functions===

Ionic let pages define some functions that will be called when certain navigation lifecycle events happen. For more info about these functions, see [https://ionicframework.com/blog/navigating-lifecycle-events/ this page].

You can define these functions in your plugin javascript:

<code javascript>
this.ionViewCanLeave = function() {
...
};</code>

So for example you can make your plugin ask for confirmation if the user tries to leave the page when he has some unsaved data.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]

Moodle App Plugins Development Guide

2019-12-20T14:54:46Z

Dpalou: /* Options only for CoreCourseOptionsDelegate */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.
* '''ismenuhandler''': (optional) Supported from the 3.7.1 version of the app. Set it to true if you want your plugin to be displayed in the contextual menu of the course instead of in the top tabs. The contextual menu is displayed when you click in the 3-dots button at the top right of the course.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''method''' (optional): The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;
* '''coursepagemethod''': (optional) Supported from the 3.8 version of the app. If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML.

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return this in the init method (only for Moodle 3.8 and onwards).

<code php>
return [
'disabled' => true
];</code>

If the Moodle version is older than 3.8, then the init method should return this:

<code php>
return [
'javascript' => 'this.HANDLER_DISABLED'
];</code>

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

===Implement a module similar to mod_label===

In Moodle 3.8 or higher, if your plugin doesn't support ''FEATURE_NO_VIEW_LINK'' and you don't specify a ''coursepagemethod'' then the module will only display the module description in the course page and it won't be clickable in the app, just like mod_label. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in ''displaydata'').

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the property ''coursepagemethod'' in the mobile.php. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only default HTML.

If you don't want your module to be clickable then you just need to remove the ''method'' from mobile.php. With these 2 changes you can have a module that behaves like mod_label in the app.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]

Moodle App Plugins Development Guide

2019-12-20T14:41:33Z

Dpalou:

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''method''' (optional): The function to call to retrieve the main page content. In this delegate the method is optional. If the method is not set, the module won't be clickable.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;
* '''coursepagemethod''': (optional) Supported from the 3.8 version of the app. If set, this method will be called when the course is rendered and the HTML returned will be displayed in the course page for the module. Please notice the HTML returned should not contain directives or components, only default HTML.

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return this in the init method (only for Moodle 3.8 and onwards).

<code php>
return [
'disabled' => true
];</code>

If the Moodle version is older than 3.8, then the init method should return this:

<code php>
return [
'javascript' => 'this.HANDLER_DISABLED'
];</code>

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

===Implement a module similar to mod_label===

In Moodle 3.8 or higher, if your plugin doesn't support ''FEATURE_NO_VIEW_LINK'' and you don't specify a ''coursepagemethod'' then the module will only display the module description in the course page and it won't be clickable in the app, just like mod_label. You can decide if you want the module icon to be displayed or not (if you don't want it to be displayed, then don't define it in ''displaydata'').

However, if your plugin needs to work in previous versions of Moodle or you want to display something different than the description then you need a different approach.

If your plugin wants to render something in the course page instead of just the module name and description you should specify the property ''coursepagemethod'' in the mobile.php. The template returned by this method will be rendered in the course page. Please notice the HTML returned should not contain directives or components, only default HTML.

If you don't want your module to be clickable then you just need to remove the ''method'' from mobile.php. With these 2 changes you can have a module that behaves like mod_label in the app.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]

Moodle App Plugins Development Guide

2019-12-20T14:18:29Z

Dpalou: /* Display the plugin only if certain conditions are met */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return this in the init method (only for Moodle 3.8 and onwards).

<code php>
return [
'disabled' => true
];</code>

If the Moodle version is older than 3.8, then the init method should return this:

<code php>
return [
'javascript' => 'this.HANDLER_DISABLED'
];</code>

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]

Moodle App Plugins Development Guide

2019-12-20T14:03:44Z

Dpalou: /* Options only for CoreBlockDelegate */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": Your block will only display the block title, and when it's clicked it will open a new page to display the block contents (the template returned by the block's method).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should throw an exception in this init method. It's recommended to include a message explaining why the plugin isn't available for the current user, this exception will be logged in the Javascript console.

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]

Moodle App Plugins Development Guide

2019-12-20T13:29:05Z

Dpalou:

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should throw an exception in this init method. It's recommended to include a message explaining why the plugin isn't available for the current user, this exception will be logged in the Javascript console.

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)

=== Mobile app support award ===

If you want your plugin to be awarded in the plugins directory and marked as supporting the mobile app, please feel encouraged to contact us via email [mailto:mobile@moodle.com mobile@moodle.com].

Don't forget to include a link to your plugin page and the location of its code repository.

See [https://moodle.org/plugins/?q=award:mobile-app the list of awarded plugins] in the plugins directory

[[Category:Mobile]]