MoodleDocs - User contributions [en]

Moodle Mobile 2 (Ionic 1) Customization

2022-04-29T07:14:36Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 2 (Ionic 1)}}
IMPORTANT: This documentation will be obsolete in May 2018, please [https://moodle.org/mod/forum/discuss.php?d=360412 read this announcement].
== Overview ==
Moodle Mobile can be customized in different ways:
* Changing the app appearance for your site.
* Creating a set of remote add-ons in order to add additional functionalities to the app.
* Creating a custom application (with your custom name and icon) based on the Moodle Mobile code.
* Configuring how the app should work via Moodle site settings.
With the first two options you are not required to compile or build your custom application, with the third one you are required to compile and publish your custom app in the stores.
== Changing the app appearance for your site ==
The Mobile app can retrieve your custom styles from your Moodle site. Since is an HTML5 app, you can apply safely CSS3 styles.

In your Moodle installation go to Plugins / Web services / Mobile and enter in the mobilecssurl field a valid URL pointing to a CSS file containing your custom styles (theme).

The CSS should be placed inside your Moodle installation (in your custom theme or inside a local plugin)

Once the user is logged in the app, there is a periodical process that retrieves your remote CSS files for applying your custom styles into the app.

Notice that on the first time a user opens the app, he will see the default "orange" style. Your custom styles will be applied once the user has added a site in the app.

Notice also that styles comes from a site, there is no way for changing the initial Add site / Manage account pages styles.

See [[Moodle Mobile Themes]] for additional information.
== Remote add-ons ==
Remote add-ons are available since Moodle 3.1 and Moodle Mobile 3.1.

A Moodle Mobile remote add-on is the mobile app version of a Moodle plugin that will be loaded when a user accesses the site on the app.

Moodle Mobile remote add-ons are stored within a Moodle plugin and are downloaded and lazy-loaded by the Mobile app in every site that uses them.

Remote add-ons are the best choice if you just want to support a Moodle plugin in the Mobile app without having to create and maintain a custom version.

See [[Moodle Mobile Remote add-ons]] for complete information.
== Creating a custom application ==
See [[Moodle Mobile custom apps]] or [https://moodle.com/mobileapp/ The Branded Moodle Mobile App service] by Moodle HQ
=== Building ===
There are two options for building the app, aka compile it to different devices:

'''Phonegap Build'''

Phonegap Build is an online service that lets you build the app automatically for different platforms. The main advantage is that it simplifies a lot the process of building.

You just put your www/ folder in a github account and Phonegaps automatically builds the app for different platforms pulling your github code.

Notice that the free version is for open repositories, but you can use the non-free version for private repositories.

In order to build your app using Phonegap Build you need to place a special config.xml file into the www/ folder, see the config.xml file for Moodle Mobile 2 (Please, note that this file is different from the one created by Ionic in the app root folder). Please follow the tutorial mentioned in [[Moodle Mobile custom apps]] to view all the steps required for building the app using Phonegap Build service.

'''Ionic CLI'''

You can also build the app using the Ionic CLI tools, see: http://ionicframework.com/docs/cli/run.html
== Configuring how the app should work via Moodle site settings ==
The app can be configured via Moodle site settingss. You can disable features, rename strings, add new elements to the main menu or change how log out works in the app. This requires Moodle 3.3 or the [[https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin]].

Please refer to the Configuring the app from your site section in this page: https://docs.moodle.org/en/Moodle_Mobile_guide_for_admins
== Testing and developing ==
=== Chromium or Google Chrome browser ===
See [[Moodle Mobile development using Chrome or Chromium]]
== Moodle Desktop ==
Refer to [[Moodle Desktop]]
== See also ==
[https://moodle.com/mobileapp/ Branded Moodle Mobile app service by Moodle HQ]

Moodle Mobile 2 (Ionic 1) Developing a plugin tutorial

2022-04-29T07:14:32Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 2 (Ionic 1)}}

IMPORTANT: This documentation will be obsolete in May 2018, please [https://moodle.org/mod/forum/discuss.php?d=360412 read this announcement].

== Introduction ==

This tutorial describes all the steps needed for developing an add-on for the Moodle Mobile app.

In this tutorial we make the following assumptions:

* You have a medium/good skills/understand of AngularJS/Ionic, PHP and Moodle architecture
* You know what a Web Service is and how it works in Moodle
* The plugin you are going to develop requires a Web Service in your Moodle installation to work

There is a second part of this tutorial where we extend the add-on features [[Moodle Mobile Developing a plugin tutorial part 2]]

== Add-on spec ==

We want to develop a plugin that will display a new button in the user profile for adding new notes to the user. This plugin is suitable for course managers of teachers.

A couple of screenshots with the desired result:

{|
| [[File:MoodleMobile2Tutorial01.png|thumb|Initial view]]
| [[File:MoodleMobile2Tutorial02.png|thumb|Course contents view]]
|}

== Steps ==

=== Set up your development environment ===

Please, read [[Setting up your development environment for Moodle Mobile 2]]

=== Set up your Moodle installation ===

Enable debugging, disable caches, etc... the typical settings for developing.

Enable the Mobile Service via Admin / Plugins / Web Services / Mobile

=== Develop the Moodle Web Services you are going to need ===

In this case we'll use an existing web service (core_notes_create_notes) that is already available in the Moodle Mobile app service, if you need custom functions you will need to develop a local plugin including there your new Web Services (see https://moodle.org/plugins/view/local_wstemplate) and create a custom service.

=== Develop the Moodle Mobile add-on ===

The full source code can be found here: https://github.com/moodlehq/moodlemobile2/tree/master/www/addons/notes

'''www/addons/notes/main.js'''
<syntaxhighlight lang="javascript">
angular.module('mm.addons.notes', [])

.run(function($mmUserDelegate, $mmaNotesHandlers) {

$mmUserDelegate.registerPlugin('mmaNotes:addNote', $mmaNotesHandlers.addNote);

});
</syntaxhighlight>

Here we declare the plugin, and register the Plugin (this means that the plugin will be displayed in the User profile.

We will use the $mmaNotesHandlers service for holding all the code related to the plugin availability and main functions

There are more delegates for registering your plugin, see:
* www/addons/mod_forum/main.js (Module delegate, and module actions delegate)
* www/addons/messages/main.js (Main side menu delegate, and multiple delegates for the user profile)

'''www/addons/notes/services/handlers.js'''
<syntaxhighlight lang="javascript">

self.isEnabled = function() {
return $mmaNotes.isPluginEnabled();
};

self.isEnabledForUser = function(user, courseId) {
// Active course required.
return courseId && user.id != $mmSite.getUserId();
};
</syntaxhighlight>

These are mandatory functions that will check our plugin availability, the first one will rely in the $mmaNotes service (isPluginEnabled function), the second ones checks that the user profile is being viewed inside a course (because the WS requires it) and that the current user is not the required user (so you don't see the buttons in your own profile).

<syntaxhighlight lang="javascript">

self.getController = function(user, courseid) {

return function($scope) {

// Button title.
$scope.title = 'mma.notes.addnewnote';

$ionicModal.fromTemplateUrl('addons/notes/templates/add.html', {
scope: $scope,
animation: 'slide-in-up'
}).then(function(m) {
$scope.modal = m;
});

$scope.closeModal = function(){
$scope.modal.hide();
};

$scope.addNote = function(){
// Freeze the add note button.
$scope.processing = true;

$mmaNotes.addNote(user.id, courseid, $scope.note.publishstate, $scope.note.text).then(function() {
$translate('mma.notes.eventnotecreated').then(function(str) {
$ionicLoading.show({
template: str,
duration: 2000
});
});
}, function(error) {
$mmUtil.showErrorModal(error);
}).finally(function() {
$scope.closeModal();
});
};

$scope.action = function($event) {
$event.preventDefault();
$event.stopPropagation();

$scope.note = {
publishstate: 'personal',
text: ''
};
$scope.processing = false;

$scope.modal.show();
};
};
};

</syntaxhighlight>

These is the main function code, it does the following:
* $scope.title = 'mma.notes.addnewnote'; This sets the button title, note that we reference to the addnewnote string that is in the www/addons/notes/lang/en.json file (we need to prefix the string id to identify the plugin)
* $ionicModal.fromTemplateUrl - Creates the modal we are going to use for displaying the form, the HTML code of the form is in www/addons/notes/templates/add.html
* $scope.closeModal - Helper function for closing the modal inside the modal via a button
* $scope.addNote - This function will be called when the user clicks the "Add a note" button in the modal, it will use the $mmaNotes service that handles all the logic WS logic for creating the note
* $scope.action - This function will be called when the user clicks the "Add a note" button in the user profile view, it will open the modal and set the default values

'''www/addons/notes/services/notes.js'''
<syntaxhighlight lang="javascript">

angular.module('mm.addons.notes')

.factory('$mmaNotes', function($mmSite, $log, $q) {
$log = $log.getInstance('$mmaNotes');

var self = {};

self.addNote = function(userId, courseId, publishState, noteText) {
var data = {
"notes[0][userid]" : userId,
"notes[0][publishstate]": publishState,
"notes[0][courseid]": courseId,
"notes[0][text]": noteText,
"notes[0][format]": 1
};
return $mmSite.write('core_notes_create_notes', data);
};

self.isPluginEnabled = function() {
var infos;

if (!$mmSite.isLoggedIn()) {
return false;
} else if (!$mmSite.canUseAdvancedFeature('enablenotes')) {
return false;
} else if (!$mmSite.wsAvailable('core_notes_create_notes')) {
return false;
}

return true;
};

return self;
});
</syntaxhighlight>

This file contains the notes service:
* isPluginEnabled - Checks if the notes functionality is available by checking Moodle settings and the required WS availability
* addNote - Will call the remote WS for adding the note via the $mmSite.write helper method (the $mmService has also a read method for retrieving data)

'''/www/addons/notes/templates/add.html'''
<syntaxhighlight lang="html4strict">
<ion-modal-view class="product edit create">
<form name="itemEdit" ng-submit="addNote()">
<ion-header-bar class="bar-header">
<h1 class="title">{{ 'mma.notes.addnewnote' | translate }}</h1>
<a class="button" ng-click="closeModal()">{{ 'mm.core.cancel' | translate }}</a>
</ion-header-bar>
<ion-content has-bouncing="true">
<div class="row">
<div class="col">
<label class="item item-input item-select">
<div class="input-label">
{{ 'mma.notes.publishstate' | translate }}
</div>
<select ng-model="note.publishstate" name="publishstate">
<option value="personal">{{ 'mma.notes.personalnotes' | translate }}</option>
<option value="course">{{ 'mma.notes.coursenotes' | translate }}</option>
<option value="site">{{ 'mma.notes.sitenotes' | translate }}</option>
</select>
</label>
</div>
</div>
<div class="row">
<div class="col">
<label class="item item-input text">
<textarea placeholder="{{ 'mma.notes.note' | translate }}" rows="5" ng-model="note.text" name="text" lose-focus-on-return required="required"></textarea>
</label>
</div>
</div>
<div class="padding">
<button type="submit" class="button button-block" ng-disabled="processing || !note.text.length || note.text.length < 2">
{{ 'mma.notes.addnewnote' | translate }}
</button>
</div>
</ion-content>
</form>
</ion-modal-view>
</syntaxhighlight>

This file includes the code for the modal. As you can see the close button will call the closeModal() function meanwhile the Add a note button will submit the form that will invoke the addNote function

For more information, refer to http://ionicframework.com/docs/api/service/$ionicModal/

== See also ==

[[Moodle Mobile Developing a plugin tutorial part 2]]

[[Category: Tutorial]]

Moodle Mobile 2 (Ionic 1) Developing a plugin tutorial part 2

2022-04-29T07:14:29Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 2 (Ionic 1)}}

IMPORTANT: This documentation will be obsolete in May 2018, please [https://moodle.org/mod/forum/discuss.php?d=360412 read this announcement].

== Introduction ==

In this tutorial we are going to extend the notes add-on functionality

== Add-on spec ==

We want to develop a plugin that will display a new option at course level (at the same line that contents, participants and grades).

This option will display all the course notes for all the participants in the course (it's suitable for teachers).

A couple of screenshots with the desired result:

{|
| [[File:MoodleMobile2Tutorial201.png|thumb|Initial view]]
| [[File:MoodleMobile2Tutorial202.png|thumb|Note types view]]
| [[File:MoodleMobile2Tutorial203.png|thumb|Notes view]]
|}

== Steps ==

=== Set up your development environment ===

Please, read [[Setting up your development environment for Moodle Mobile 2]]

=== Set up your Moodle installation ===

Enable debugging, disable caches, etc... the typical settings for developing.

Enable the Mobile Service via Admin / Plugins / Web Services / Mobile

=== Develop the Moodle Web Services you are going to need ===

In this case we'll use an existing web service (core_notes_get_course_notes) that is already available in the Moodle Mobile app service, if you need custom functions you will need to develop a local plugin including there your new Web Services (see https://moodle.org/plugins/view/local_wstemplate) and create a custom service.

=== Develop the Moodle Mobile add-on ===

The full source code can be found here: https://github.com/moodlehq/moodlemobile2/tree/master/www/addons/notes

'''www/addons/notes/main.js'''
<syntaxhighlight lang="javascript">
angular.module('mm.addons.notes', [])

.config(function($stateProvider) {

$stateProvider

.state('site.notes-types', {
url: '/notes-types',
views: {
'site': {
templateUrl: 'addons/notes/templates/types.html',
controller: 'mmaNotesTypesCtrl'
}
},
params: {
course: null
}
})

.state('site.notes-list', {
url: '/notes-list',
views: {
'site': {
templateUrl: 'addons/notes/templates/list.html',
controller: 'mmaNotesListCtrl'
}
},
params: {
courseid: null,
type: null
}
});
})

.run(function($mmUserDelegate, $mmaNotesHandlers, $mmCoursesDelegate, $mmaNotes) {

// Register plugin on course list.
$mmCoursesDelegate.registerPlugin('mmaNotes', function() {

if ($mmaNotes.isPluginViewNotesEnabled()) {
return {
icon: 'ion-ios-list',
state: 'site.notes-types',
title: 'mma.notes.notes'
};
}
});
});
</syntaxhighlight>

Here we declare the plugin, and register the Plugin (this means that the plugin will be displayed in the course main menu.

Note also that we are declaring the states (views) the plugin will support, in this case there are two views:
* notes-types: Is a list that display the different note types available (site, course, personal).
* notes-lists: that will display a list of notes for the type selected in the previous view.

'''www/addons/notes/templates/types.html''' and '''www/addons/notes/templates/list.html'''

These files contains the templates used for the view, the first one is very simple since it only links to the different note types.

The second one is more complex since requires a controller that is going to do all the logic for retrieving the note and prepare them to be displayed.

'''www/addons/notes/controllers/types.js'''

This is the controller that inject data in the types.html view, the code is pretty simple:

<syntaxhighlight lang="javascript">
angular.module('mm.addons.notes')
.controller('mmaNotesTypesCtrl', function($scope, $stateParams) {
var course = $stateParams.course,
courseid = course.id;

$scope.courseid = courseid;

});
</syntaxhighlight>

It just make available in the $scope the courseid, that is required because is passed as a state parameter for the list view.

'''www/addons/notes/controllers/list.js'''

This controller is the one that will render in the list view the notes:

<syntaxhighlight lang="javascript">
.controller('mmaNotesListCtrl', function($scope, $stateParams, $mmUtil, $mmaNotes, $mmSite, $translate) {

var courseid = $stateParams.courseid,
type = $stateParams.type;
</syntaxhighlight>
Here we retrieved the state parameters (the course id and the type of notes) that were declared in the types.html view.

<syntaxhighlight lang="javascript">
function fetchNotes(refresh) {
return $mmaNotes.getNotes(courseid, refresh).then(function(notes) {
notes = notes[type + 'notes'];

return $mmaNotes.getNotesUserData(notes, courseid).then(function(notes) {
$scope.notes = notes;
});

}, function(message) {
$mmUtil.showErrorModal(message);
});
}
</syntaxhighlight>
The fetchNotes function is responsible of using the Notes service getNotes to retrieve the data, note that we use an additional function getNotesUserData to retrieve the full user profile information (since via getNotes we only get the userid)

<syntaxhighlight lang="javascript">
fetchNotes().then(function() {
// Add log in Moodle.
$mmSite.write('core_notes_view_notes', {
courseid: courseid,
userid: 0
});
})
</syntaxhighlight>
After retrieving the notes, we do logging in Moodle (so the actions are registered in the web interface)

<syntaxhighlight lang="javascript">
$scope.refreshNotes = function() {
fetchNotes(true).finally(function() {
$scope.$broadcast('scroll.refreshComplete');
});
};
</syntaxhighlight>
This function is triggered by the "Pull down to refresh" action in order to refresh the view (empty the cache), note that the true parameter in the fetchNotes function means to not use cache.

'''www/addons/notes/services/notes.js'''

The notes services holds all the main plugin logic, it's responsible of checking if the plugin is available, retrieve information for the server and format the information so it can be rendered in the view by the controller.

<syntaxhighlight lang="javascript">
self.isPluginViewNotesEnabled = function() {
var infos;

if (!$mmSite.isLoggedIn()) {
return false;
} else if (!$mmSite.canUseAdvancedFeature('enablenotes')) {
return false;
} else if (!$mmSite.wsAvailable('core_notes_get_course_notes')) {
return false;
}

return true;
};
</syntaxhighlight>
Here we checked if the plugin is enabled, the user must logged in, enablenotes should be enabled in the Moodle global settings and the core_notes_get_course_notes function should be available.

<syntaxhighlight lang="javascript">
self.getNotes = function(courseid, refresh) {

$log.debug('Get notes for course ' + courseid);

var data = {
courseid : courseid
},
presets = {};
if (refresh) {
presets.getFromCache = false;
}

return $mmSite.read('core_notes_get_course_notes', data, presets);
};
</syntaxhighlight>
Here we retrieve the notes information from Moodle via Web Services, note that the refresh function is used for invalidating the cache (for example, when the user performs a pull down to refresh).

<syntaxhighlight lang="javascript">
self.getNotesUserData = function(notes, courseid) {
var promises = [];

angular.forEach(notes, function(note) {
var promise = $mmUser.getProfile(note.userid, courseid, true);
promises.push(promise);
promise.then(function(user) {
note.userfullname = user.fullname;
note.userprofileimageurl = user.profileimageurl;
}, function() {
// Error getting profile. Set default data.
return $translate('mma.notes.userwithid', {id: note.userid}).then(function(str) {
note.userfullname = str;
});
});
});
return $q.all(promises).then(function() {
return notes;
});
};
</syntaxhighlight>
Since getNotes returns only userids, we need to retrieve the complete user information in order to be able to display his full name and profile image. We use the $mmUser service getProfile function.

[[Category: Mobile]]
[[Category: Tutorial]]

Moodle Mobile 2 (Ionic 1) Plugins Development

2022-04-29T07:14:27Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 2 (Ionic 1)}}

IMPORTANT: This documentation will be obsolete in May 2018, please [https://moodle.org/mod/forum/discuss.php?d=360412 read this announcement].

== Overview ==

Plugins (known as Moodle Mobile 2 addons) allow developers to extend the app functionalities.

An addon is a subdirectory that implements a set of required functionalities. For those familiars with AngularJS, addones are AngularJS modules.

IMPORTANT: Read carefully this document ([[Moodle Mobile Customization]]) before you start developing!

Please, note also that this documentation is oriented to Moodle Mobile specific APIs, before starting developing you should get familiar with AngularJS and Ionic, here you have some resources:

'''Ionic'''
* http://ionicframework.com - Official Ionic website
* https://www.airpair.com/ionic-framework/posts/the-definitive-ionic-starter-guide - Definitive ionic starter guide
* http://mcgivery.com/100-ionic-framework-resources/ - +100 Ionic resources
* https://github.com/juarezpaf/ionic-adventures?utm_source=mobilewebweekly&utm_medium=email - More ionic resources
* http://codepen.io/ionic/public-list/ - Ionic sample code lists
* https://www.youtube.com/channel/UChYheBnVeCfhCmqZfCUdJQw - YouTube channel from Ionic
* http://www.manning.com/wilken/ - Ionic in action book

'''Angular'''
* https://angularjs.org - The official documentation for AngularJS
* http://manning.com/bford - AngularJS in Action book
* http://manning.com/aden - AngularJS in Depth book

'''Cordova'''
* http://cordova.apache.org - Official Cordova site
* http://plugins.cordova.io - Cordova official plugin registry.
* http://ngcordova.com - ngCordova AngularJS wrappers for cordova

== Moodle Mobile 2 addons ==

Each addon can have services, controllers, templates and lang files. The addon needs to specify a main.js file to initialize the addon and to register itself into one or more delegates (this determines where will the plugin be shown).

Naming conventions for addons:
* The module name for addons needs to be mm.addons.addonname and it should be defined in the addon main.js.
* All the services names inside an addon need to start with $mma, followed by the service name in camel-case. For example, $mmaForumData.
* The controllers names need to start with mma (without dollar), followed by the controller name in camel-case. The controller name needs to contain Ctrl to easily identify it as a controller. For example, mmaForumListCtrl.

The app comes with a predefined set of addons: messages, forum, notifications, etc. All these addons are inside the www/addons folder.

An addon can be shown in several places. The app has one delegate per each place an addon can be shown, so each addon can register itself to any set of delegates.

You can see the list of available delegates [https://docs.moodle.org/dev/Moodle_Mobile#Addons in this section].

=== Structure of an addon ===

If you are not familiar with AngularJS, please, read the [https://docs.angularjs.org/guide AngularJS] guide to a complete understanding of the different terms used in this document.

Forum addon directory:

controllers/
discussion.js
discussions.js
lang/
en.json
services/
forum.js
templates/
discussion.html
discussions.html
main.js

'''controllers and templates'''

The controllers directory contains the module controllers, usually you are going to have there a controller per view and per template.

In the forum example, you can see that there are two controllers and two templates:

* discussions.js|html for displaying the complete list of discussions of a forum in a course
* discussion.js|html for displaying a single discussion.

Each controller is responsible of rendering the view, for example, the discussions.js will fetch and display the list of discussions of the forum using the helper service defined in forum.js

The controller will also implement additional functionalities like support to "Pull down to refresh"

'''lang'''

The lang directory contain the language file with the translated strings.

'''services'''

This directory contains the app services, usually for non-complex addons you will find a single file inside containing all the code logic used for providing the main functionality of the addon like the code for retrieving the discussions via Moodle Web Services.

'''main.js'''

This is a mandatory file, it:
* Creates the AngularJS module
* Declares all the state routes the plugin is going to user. Attaching a controller and template for each different state.
* Initializes the addon and register it into one or more delegates (this determines where the plugin will be displayed in the app).

== See also ==

* [[Moodle Mobile Developing a plugin tutorial]]
* [[Moodle Mobile Developing a plugin tutorial part 2]]

Moodle Mobile 2 (Ionic 1) Remote add-ons

2022-04-29T07:14:24Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 2 (Ionic 1)}}
{{Moodle 3.1}}
Only available for Moodle 3.1 onwards.

IMPORTANT: This documentation will be obsolete in May 2018, please [https://moodle.org/mod/forum/discuss.php?d=360412 read this announcement].

A Moodle Mobile remote add-on is the mobile app version of a Moodle plugin that will be loaded when a user accesses the site on the app.

Moodle Mobile remote add-ons are stored within a Moodle plugin and are downloaded and lazy-loaded by the Mobile app in every site that uses them.

Moodle plugins can include several Mobile add-ons. They can also declare dependencies between plugins.

We can say that a remote add-on is a special version of a Moodle Mobile add-on. The main differences are:
* Mobile remote add-ons are placed inside Moodle plugins (outside the Mobile app).
* Mobile remote add-ons language files must include the whole component prefix.
* Mobile remote add-ons uses special placeholders for paths inside Javascript code.

If you do not know how to develop for the Moodle Mobile app at all, you might find it useful to start with a tutorial (refer back to this page for more detailed information): [[Moodle Mobile remote add-on tutorial]]

== How to create a remote add-on ==

Remote add-ons must be developed first as standard Moodle Mobile add-ons and then packaged as a remote add-on.

These are the main required steps:

* Develop the required Moodle Web Services
* Develop a standard Moodle Mobile add-on
* Package the Moodle Mobile add-on as a remote add-on
* Include the remote add-on in your Moodle plugin

=== Web Services ===

Most of Mobile add-ons require Web Services to work, but in some cases (like add-ons implementing question types) it won't be necessary.

Please refer to [[Web services]] documentation, you have an example here: https://github.com/jleyva/moodle-mod_certificate/blob/CONTRIB-6313/classes/external.php

Once the Web Services are developed, you must include them into the Mobile (and local_mobile) service using the "services" field when declaring external functions, see: https://github.com/jleyva/moodle-mod_certificate/blob/CONTRIB-6313/db/services.php

Remember that this is only available from Moodle 3.1 onwards.

=== Mobile add-on ===

Refer to [[Moodle Mobile Plugins Development]]

If your addon registers any store to the site database ([https://github.com/moodlehq/moodlemobile2/blob/master/www/addons/calendar/services/calendar.js#L19 example]), it must execute the following code in a ''.run'' function:

if ($mmSite.isLoggedIn() && $mmSite.reloadDb) {
$mmSite.reloadDb();
}

=== Remote add-on packaging ===

==== Automatic packaging ====

The MoodleMobile app comes with a gulp task to package remote addons. This task is in the file [https://github.com/moodlehq/moodlemobile2/blob/master/gulpfile.js gulpfile.js located in the root folder].

In order to package the addon, go to the project's root folder (where the gulpfile.js is located) and run the following command:

gulp remoteaddon -p {PATHTOADDON}

For example:

gulp remoteaddon -p www/addons/mod/certificate

This command should create a ZIP file inside the addon folder. This ZIP should contain all the files required for your remote addon to work.

Options accepted by the command:

* '''--path or -p''': Required parameter. Path to the addon folder.
* '''--jspath or -jsp''': Optional. The path to replace in the Javascript files. All the matches found will be replaced by ''$ADDONPATH$'' (see [https://docs.moodle.org/dev/Moodle_Mobile_Remote_add-ons#Manual_packaging Manual packaging] for more info). If not defined we will use the same value as "path" param.
* '''--output or -o''': Optional. Path to the output ZIP file. If not defined, the ZIP will be stored in the addon's folder.

==== Manual packaging ====

Some requirements need to be met to make the remote add-on work in the app. These are the steps you need to follow in order to make it work:

* Place all the JavaScript code of your addon in a single file named ''addon.js''. This file needs to be in your addon's root folder.
* In this ''addon.js'', replace the paths to your addon folder with ''$ADDONPATH$''. For example, if you have
<nowiki>templateUrl: 'addons/myaddon/templates/index.html'</nowiki>
...
<nowiki>$scope.icon = 'addons/myaddon/icon.gif';</nowiki>
you should set it like this:
<nowiki>templateUrl: '$ADDONPATH$/templates/index.html'</nowiki>
...
<nowiki>$scope.icon = '$ADDONPATH$/icon.gif';</nowiki>
* Add your addon's prefix to language strings. That is, if you have a string like this:
<nowiki>"getcertificate": "Get your certificate"</nowiki>
you need to set it like this:
<nowiki>"mma.mod_certificate.getcertificate": "Get your certificate".</nowiki>
It's important that language files are inside a "''lang''" folder in your addon's root folder.
* It's required to have 1 language file for each language supported by the app. If you don't want to translate to a certain language then you must create a file with an empty JSON for that language. [https://github.com/moodlehq/moodlemobile-phonegapbuild/tree/master/build/lang Click here] to see the list of languages supported by the app.
* Place all the styles of your addon in a single file named ''styles.css''. This file needs to be in your addon's root folder. Please notice you don't need to use ''$ADDONPATH$'' in here, all the paths will be relative to the addon's root folder.

Once all this is done you need to create a zip file with your addon files. Please make sure that the files ''addon.js'' and ''styles.css'' are in the root of this zip file.

See https://github.com/jleyva/moodle-mod_certificate/tree/CONTRIB-6313/mobile for a zip file example for the Certificate module.

=== Remote add-on publishing ===

Once you have a zip file containing the remote add-on, you must include it into the Moodle plugin.

Please, refer to [[Activity_modules#mobile.php]] for instructions. Basically you will need to create a db/mobile.php and place the zip file into mobile/addonname.zip

== Known issues ==

* You cannot use Cordova or 3rd party plugins not used by the app. You can see the list of supported plugins here: https://github.com/moodlehq/moodlemobile-phonegapbuild/blob/master/config.xml#L112
* When creating/editing db/mobile.php during development you must bump the version or purge caches. See MDL-58590

==See also==

* List of plugins currently providing mobile app support: [https://moodle.org/plugins/browse.php?list=award&id=6 Moodle plugins directory: Award: mobile app support]

Moodle Mobile 2 (Ionic 1) Themes

2022-04-29T07:14:20Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 2 (Ionic 1)}}

IMPORTANT: This documentation will be obsolete in May 2018, please [https://moodle.org/mod/forum/discuss.php?d=360412 read this announcement].

The Mobile app can retrieve your custom styles from your Moodle site. Since is an HTML5 app, you can apply safely CSS3 styles.

In your Moodle installation go to "Administration > Site administration > Mobile app > Appearance" and enter in the mobilecssurl field a valid URL pointing to a CSS file containing your custom styles (theme).

The CSS should be placed inside your Moodle installation (in your custom theme or inside a local plugin).

Notice that on the first time a user opens the app, he will see the default "orange" style. Your custom styles will be applied once the user has added your site in the app.

Notice also that styles comes from a site, there is no way for changing the Add site / Manage account styles.

== Example of a custom theme (CSS file) ==

<syntaxhighlight lang="css">
/* Un-comment the following, for initial RTL UI support.
.scroll-content {
direction: rtl;
text-align: right;
}
*/

.bar-side-menu {
background-color: blue;
}

.bar-content {
background-color: blue;
}

.button.button-positive {
border-color: blue;
background-color: blue;
color: #fff;
}

.item-divider {
background-color: #fafafa;
}
</syntaxhighlight>

== Testing ==

Please, read [[Setting up your development environment for Moodle Mobile 2]] in order to set up a local environment for testing your custom CSS file, you should also read this document: [[Moodle Mobile development using Chrome or Chromium]].

== Styling specific pages ==

Moodle Mobile 2.9 onwards add a specific class for every page in the app (in the ion-content tag), in this way you can apply specific styles for pages.

For example, if you inspect the app you'll see things like this:

<nowiki><ion-content class="mm-site_mm_courses">...</ion-content></nowiki>

== Files referenced in the CSS files ==

Moodle Mobile 3.1.0 onwards automatically download the files referenced in the CSS for offline usage. Please notice that data URLs aren't downloaded.

== CSS and files synchronization ==

The CSS file and the referenced files will be downloaded or updated when the user starts the app or accesses your site. Please notice that the downloaded files are updated only if the file URL changes or the user synchronizes the site data in App Settings.

If you want to update a file without changing the file location you can add a prefix to the file URL. Example: {SITEURL}/myimage.png'''#1'''.

== Useful selectors ==

Here's a list of useful selectors to customize the application.
You can always navigate to: http://prototype.moodle.net/mobile/webapp (which is connected to https://school.demo.moodle.net) and use the username "teacher" and password "moodle" to log in, and then use the browser's developer tools (F12 or Inspect) to figure out all the IDs and classes for your CSS selectors.

=== App header ===

* '''Class ''.bar-header''''': To customize the header of the application and the side menu (shown in all screens).

* '''Class ''.bar-side-menu''''': To customize only the side menu header..

* '''Class ''.bar-content''''': To customize only the content header, not the side menu.

=== Side menu ===

* '''Element ''ion-side-menu''''': All the elements shown in a side menu (either left or right) are inside this element.

* '''Attribute ''side''''': Useful to distinguish between left and right side menu. Example:

ion-side-menu[side="left"]
ion-side-menu[side="right"]

* '''IDs ''mm-side-menu-left'' and ''mm-side-menu-right''''': Also useful to distinguish between left and right side menu. Example:

#mm-side-menu-left
#mm-side-menu-right

* '''Class ''.item''''': Every item in the side menu has this class. This class is common in the whole app, please see Ionic styles. For example, if you want to apply a style to all the items in the side menu you can use the selector:

ion-side-menu li .item, ion-side-menu li.item

* '''Class ''.item-divider''''': To customize the divider that splits the side menu list in two. This class is common in the whole app, please see Ionic styles.

=== Icons ===

The app usually uses Ionic icons, identified by a class. If you want to change an icon to use your own you should search the class that identifies the icon (usually starts with ion-) and override the content.

For example:

<nowiki>.ion-ionic:before {
content: "\f3ea";
}</nowiki>

You can see the whole list of Ionic icons [http://ionicons.com in the Ionicons web].

You can see the unicode value for a certain Ionic icon near the icon name in [https://raw.githubusercontent.com/moodlehq/moodlemobile-phonegapbuild/master/lib/ionic/fonts/ionicons.svg this file].

=== Ionic styles ===

The application is built using the Ionic framework, and so it contains a lot of elements and styles defined by Ionic.

You can see a list of common Ionic elements in the [http://ionicframework.com/docs/components/ Ionic CSS Components web].

== See also ==

* [http://www.slideshare.net/juanleyva/creating-moodle-mobile-remote-themes Creating Moodle Mobile themes] - A presentation in the MoodleMoot UK 2016
* [https://www.slideshare.net/DaniPalouSala/creating-moodle-mobile-remote-themes-moodle-moot-us-2016 Same presentation updated for the MoodleMoot USA 2016] - Includes an example to add a logo at the top of the side menu
* http://caniuse.com/ Support tables for CSS3 styles (including Mobile browsers)

[[Category: Mobile]]

Moodle Mobile 2.0 spec

2022-04-29T07:14:17Z

Pferre22:

{{Template:WillNotMigrate}}
{{obsolete}}

<p class="note">For development documentation about Moodle Mobile 2 please refer to: [[Moodle Mobile]]</p>

==Introduction==
This document is about the future of the Moodle Mobile app, focusing on technical aspects exclusively.

This document describes the current problems and improvements needed by the app. It also discusses improvements to be done in the development process of the app.

It has been a long time since the first version of the app was designed; in 2012 the mobile scene was very different than today: Android 2.1, 2.3 and iOS 5 were the most used versions, HTML5 support in general terms was pretty limited, there were no frameworks for creating hybrid apps, Phonegap was in earlier versions, etc.

After an initial analysis, we chose to create our app using mainly jquery and backbone (avoiding all the current framework, libraries due to the performance problems). At the time AngularJS was also an option, but we discarded it since it wasn’t as popular as it is now—no one was using it for creating mobile apps back then: [https://docs.google.com/document/d/15QQaBO176IDI97mfT0Fa8nWPeejOx3uO_EnM4fANPmA/edit https://docs.google.com/document/d/15QQaBO176IDI97mfT0Fa8nWPeejOx3uO_EnM4fANPmA/edit]

Today, Android 4 and iOS 7 are the dominant operating systems/versions. HTML5 support on those devices has improved significantly and there are several frameworks oriented to create hybrid mobile apps focused on performance.

The app has currently some technical problems that would be resolved with that framework (although not all). Some problems are related to the user interface, layout/design and usability of the application; others are more specific for javascript/devices/platforms and some problems will not be resolved choosing a different framework.

* Design, usability:
::All the design and usability patterns are done from scratch; we need a framework that will take care of that so nothing breaks in major platforms changes (as already happened with iOS 8, Android 4.4, Android 5)
* Touch events responsiveness:
::The current app does not deal with that satisfactory; we need to migrate to a library supporting touch events natively, capable of detecting the device correctly for using the correct events
* Using Chrome simulators:
::Due to the problem related to touch events, we can’t use Chrome simulator for testing the apps
* Web components:
::We do not use any library for web components (like lists) and every time we need to add something new we have to do it from scratch, testing that is works “properly” in all the devices we support
* Support for CSP:
::The app uses Backbone template system which is not compatible with CSP
* Infinite scroll:
::This can be categorized as a web component
* Pull down refresh:
::This can be categorized as a web component too
* Animations performance:
::We do not use hardware/CSS3 animations
* Unit testing:
::There is no support for unit tests
* Security:
::The app uses a global object that has access to the global scope and the plugins scope
* RTL languages support:
::The app doesn’t support RTL right now
* Build process:
::We should start doing some automatization of common tasks using Grunt, etc. Some tasks are currently done in shell scripts, php, but there is no process of continuous integration/testings
* Storage:
::The app uses localStorage limited to 5MB
* Background processes:
::The current app has some memory problems due to the current sync process that is done in the main thread

In this document I’m not going to do an analysis of all the available frameworks. There are tons of articles regarding this issue in Internet, we have chosen these two:

* About mobile specific frameworks:
::[http://www.agingcoder.com/programming/2014/10/16/mobile-frameworks-onsenui/ http://www.agingcoder.com/programming/2014/10/16/mobile-frameworks-onsenui/]
* About javascript frameworks:
::[http://www.airpair.com/js/javascript-framework-comparison?utm_source=javascriptweekly&utm_medium=email http://www.airpair.com/js/javascript-framework-comparison?utm_source=javascriptweekly&utm_medium=email]

Also, I’ve been in some local events related to Mobile frameworks (locals meetup in Barcelona, BarcelonaJS group, AngularJS Barcelona group) talking with people and analyzing the advantages and disadvantages of different mobile frameworks.

In conclusion, it seems that Ionic framework (based on AngularJS) is the right choice.

==Reasons to use AngularJS/ionic framework==

* Object observer webkit implementation!!
::[http://georgestefanis.com/blog/2014/03/25/object-observe-ES7.html http://georgestefanis.com/blog/2014/03/25/object-observe-ES7.html]
* AngularJS is a framework that supports all the functionalities currently covered by 3rd party libs
* It’s focused in hybrid apps with Phonegap/Cordova
* Components are tested in different Android and iOS versions
* It’s very popular (big developer base): 20,000 aps per month are using it
* Huge knowledge base, 1400 questions in stackoverflow
* Because AngularJS was chosen by the Ionic framework “rival” Onsen components
* AngularJS is supported by Google
* It supports CSP (https://developer.mozilla.org/en-US/docs/Web/Security/CSP) so it’s a framework valid for creating Firefox OS compatible apps
* Interesting functionalities: Unit tests coverage (Jasmine), CSP support, infinite scroll, pull down refresh, hardware accelerated transitions/effects,
* MVC - Using directives (no more DOM manipulation):
::It will reduce the code base to maintain
::Ionic comes with emulators and extremely useful build and testing tools; we won’t need our simulator anymore
* Very good integration with GruntJS, Yeoman, Istambul, Jasmine etc.

===Disadvantages===
* Steep learning curve of AngularJS. For newcomers, AngularJS is a very popular framework between javascript developers, it can be easier to find AngularJS developers than developers knowing all the libraries currently used by the app.
* In older devices the app may run slow (but according to the last Moodle Mobile survey, users of Moodle are mostly using new devices)
* Angular is going to be rewritten for version 2.
* Ionic is still beta (it was alpha a couple of months ago)
* Angular only works for Android 4 and above. Firefox OS and Windows Phone seem not to be officially supported (although they are in the roadmap)

===Conclusions===
* Ionic seems to be the best candidate as framework for the app.
* It’s popular (don’t forget that Moodle popularity is partially due to PHP we don’t have to forget that Moodle becomes so popular by the use of PHP), it uses AngularJS that has a big learning curve (although due to its popularity there is plenty of documentation and javascript developers using it).
* Moodle Mobile 2 release is planned for July/August 2015, so there will be less older devices and Ionic will not be a beta anymore. Angular 2 may have been published by then (and supported by Ionic) but even if it wasn’t, Google has more than a thousand of apps using Angular 1, so it will be supported for a few more years: http://eisenbergeffect.bluespire.com/all-about-angular-2-0/?utm_source=javascriptweekly&utm_medium=email

==Roadmap==
* In order not to stop the current development of the app ([http://www.joelonsoftware.com/articles/fog0000000069.html http://www.joelonsoftware.com/articles/fog0000000069.html]), a small team should do the migration in parallel.
* An initial working prototype with static data should be implemented displaying all the current features of the app, supporting both phones and tablets.
::This prototype must be validated by Martin and Barbara, and afterwards a new phase of technical analysis of how to migrate the current architecture should start. This analysis should evaluate (among others):
* How to migrate the current plugin system to the AngularJS modules system
* How to implement the current core api function that uses jQuery (mainly the ajax requests) (use factories, services, etc..)
* Which storage system to use (keep localStorage, indexdb…)
* Background processes using webworkers (now that is better supported in modern devices)
* Continuous integration, testing, automatic tasks…

== References, interesting articles ==

Large apps:
http://www.pseudobry.com/building-large-apps-with-angular-js/
https://gocardless.com/blog/building-a-large-angular-application/
https://github.com/angular-app/angular-app

https://github.com/angular/angular.js/wiki/Projects-using-AngularJS

Tutorials:
https://thinkster.io/angulartutorial/a-better-way-to-learn-angularjs/

Translating/internationalization:
http://plnkr.co/edit/Hw4iMz?p=info
http://mcgivery.com/internationalization-of-an-ionic-app-multilanguage-support/

Angular directives list (curated)
http://angular-js.in/

Angular 2:
http://eisenbergeffect.bluespire.com/all-about-angular-2-0/?utm_source=javascriptweekly&utm_medium=email

[[Category: Mobile]]

Moodle Mobile Automatic Building System

2022-04-29T07:14:16Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle App (Ionic 3)}}

{{obsolete}}
== Introduction ==

An automatic building system helps developers a lot, they can focus on writing good code and forget all about building/compiling and all the boring stuff.

Phonegap Build is an example of a powerful build system, but it has a big limitation for Moodle Mobile; it doesn't support some Phonegap plugins we use for the Android app.

Implementing an automatic building system for Android is quite simple using 3rd party applications as described bellow:

== Automatic Build System for Android ==

=== Requirements ===

* The MoodleMobile .apk file or your custom app .apk file. You need to perform an initial build on Android. See [[Moodle Mobile Building the app for Android]] for more info or obtain the current .apk file from Google Play using software like real apk leecher

* android-apktool - http://code.google.com/p/android-apktool/

* jarsigner - Part of the Java JDK

=== Steps ===

1 Extract your .apk file template in a directory (apktool d path/to/yourApp.apk path/to/output-folder)

2 Download from moodlehq/moodlemobile repository the last files to -> path/to/output-folder/assets/www directory (where all the html, css, js files are stored)

3 Re-build the .apk file (apktool b path/to/output-folder path/to/yourAppV2.apk )

4 Re-sign the .apk file (jarsigner -verbose -keystore ~/.android/debug.keystore path/to/yourAppV2.apk androiddebugkey)

That's all, as you can see once you haven an original .apk file, extract, add your modifications and re-package is very simple

=== Automatic script ===

Say you have:

1 /opt/moodlemobile/repository/...
2 /opt/moodlemobile/apk-templates/myapp.apk
3 /opt/moodlemobile/tmpdir
4 /opt/moodlemobile/certificates

1 A cloned git repository of your code

2 Your original .apk file built with Android SDK

3 An empty dir

4 Certificate key store dir. The keystore is created using keytool, see http://docs.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html
Also see: http://developer.android.com/tools/building/building-cmdline.html and http://developer.android.com/tools/publishing/app-signing.html

The script

cd /opt/moodlemobile
rm -rf tmpdir/*
cd repository
git pull
cd ../
apktool d apk-templates/myapp.apk tmpdir/
cp -r repository/* tmpdir/assets/www/
vi tmpdir/AndroidManifest.xml (debug must be false, bump version code and change version name)
apktool b tmpdir mynewapp.apk
jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore certificates/keystore mynewapk.apk mycertificatealiasinsidekeystore
jarsigner -verbose -verify -keystore certificates/keystore mynewapk.apk ** Optional
zipalign -v 4 mynewapk.apk mynewapkReadyForPlayStore.apk

== See also ==

https://github.com/jleyva/moodlemobile-scripts For sample code

Moodle Mobile Building the app for Android

2022-04-29T07:14:12Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle App (Ionic 3)}}
Remember that you can also build the app using an external system called Phonegap Build, see [[Moodle_Mobile_Customization#Building]]
{{obsolete}}

== Installing the Android SDK ==
Building the app for Android is easy once you have successfully installed all the required software.

Since we are using Phonegap as framework for creating the app, the documentation you have to follow is just in this link plus additional steps for installing plugins:
<s>docs.phonegap.com/en/guide_getting-started_android_index.md.html#Getting%20Started%20with%20Android</s>

Notice the following:
* You must read carefully the document and not use white spaces in some names and ids. (It's adviced in the document)
* You can optionally not use Eclipse and instead use adb command line or cordova script tools
* In the "4. Setup New Project" The package_name is the app id that your app will have in the Android Market (Play Store), so it must be unique. If you are going to develop for the official app you have to use com.moodle.moodlemobile, if you are going to develop a custom app, you will have to add your own unique id.
* If you want to connect a Device to your Eclipse and you are using Windows, you must install the Android USB Drivers, see http://developer.android.com/tools/extras/oem-usb.html#InstallingDriver
== Add the Mobile app HTML5 files ==
Go to your project folder, assets/www and add just there all the files from https://github.com/moodlehq/moodlemobile
== Installing additional Phonegap plugins ==
The Android app requires two additional Phonegap plugins to be installed:
=== WebIntent ===
For opening files according their mime type: https://github.com/phonegap/phonegap-plugins/tree/DEPRECATED/Android/WebIntent

For installing the plugin follow this instructions: https://github.com/phonegap/phonegap-plugins/blob/DEPRECATED/Android/WebIntent/README.md#adding-the-plugin-to-your-project
== Build, compile, test your app ==
We suggest you to use Eclipse tools for testing, deploying the app

In any case, you can always use the Cordova command line tools.

The cli tools are in your project folder, directory cordova
== Signing your app ==
''The Android system requires that all installed applications be digitally signed with a certificate whose private key is held by the application's developer. The Android system uses the certificate as a means of identifying the author of an application and establishing trust relationships between applications. The certificate is not used to control which applications the user can install. The certificate does not need to be signed by a certificate authority: it is perfectly allowable, and typical, for Android applications to use self-signed certificates.'' See: http://developer.android.com/tools/publishing/app-signing.html

And also for Eclipse: http://developer.android.com/tools/publishing/app-signing.html#ExportWizard
== Uploading your custom app to the Google Play Store ==

== Build the official Moodle Mobile app on a Mac ==
# Install SDK
#*http://developer.android.com/sdk/index.html#download - it will install Eclipse / ADT plugin / Android SDK
# Add the SDK tools/platform-tools folders to your PATH
# Install NodeJs
#*http://nodejs.org/
# Install cordova-cli
#* ''sudo npm install -g cordova'' - it will install cordova. Note that on my machine I have some warnings about the android bootstrap process being skipped but all the following steps seem to work ok anyway...
# Create a Android project
#*''/usr/local/lib/node_modules/cordova/bin/cordova create ~/Apps/moodlemobile_android_cordova com.moodle.moodlemobile MoodleMobileBeta''
#* ''cd ~/Apps/moodlemobile_android_cordova''
#* ''sudo /usr/local/lib/node_modules/cordova/bin/cordova platform add android''
#* ''sudo /usr/local/lib/node_modules/cordova/bin/cordova build'' - not necessary, just check the build works.
# In Finder change the permission on ~/Apps/moodlemobile_android_cordova folder: Read + Write to everyone
# Open eclipse, add a new Android project from existing source pointing to /Users/jerome/Apps/moodlemobile_android_cordova/platforms/android. Test you can build the default Cordova app on your phone.
# Copy the Moodle mobile app into assests/www folder
#* ''git clone git://github.com/moodlehq/moodlemobile.git ./moodlemobile''
#* ''mv platforms/android/assets/www/ platforms/android/assets/www_old/''
#* ''mv ./moodlemobile/ platforms/android/assets/www/''
#* ''cp platforms/android/assets/www_old/cordova.js platforms/android/assets/www/''
# Add the cordova plugins
#* ''git clone git://github.com/alunny/ChildBrowser.git ./ChildBrowser'' - we are now going to install cordova compatible plugin with the plugin install command line.
#* ''sudo /usr/local/lib/node_modules/cordova/bin/cordova plugin add ChildBrowser/''
# Add manually phonegap plugins
#* ''git clone git://github.com/phonegap/phonegap-plugins.git ./phonegap-plugins''
#* ''cp phonegap-plugins/Android/WebIntent/webintent.js platforms/android/assets/www/''
#* ''mkdir platforms/android/src/com/borismus''
#* ''mkdir platforms/android/src/com/borismus/webintent''
#* ''cp phonegap-plugins/Android/WebIntent/WebIntent.java platforms/android/src/com/borismus/webintent''
#* In Eclipse, add a package to src folder. The value should be com.borismus.webintent
#* In your res/xml/config.xml file, add ''<plugin name="WebIntent" value="com.borismus.webintent.WebIntent" />'' where you define the plugins.
# copy the icons
#* ''cp platforms/android/assets/www/img/icon/android/icon-36-ldpi.png platforms/android/res/drawable-ldpi/icon.png''
#* ''cp platforms/android/assets/www/img/icon/android/icon-48-mdpi.png platforms/android/res/drawable-mdpi/icon.png''
#* ''cp platforms/android/assets/www/img/icon/android/icon-72-hdpi.png platforms/android/res/drawable-hdpi/icon.png''
#* ''cp platforms/android/assets/www/img/icon/android/icon-96-xhdpi.png platforms/android/res/drawable-xhdpi/icon.png''
# Edit the AndroidManifest.xml
#* increment ''android:versionCode="359" android:versionName="1.2.0.2"''
#* keep the following permissions: ''INTERNET, RECORD_AUDIO, RECORD_VIDEO, READ_CONTACTS, WRITE_CONTACTS, WRITE_EXTERNAL_STORAGE, ACCESS_NETWORK_STATE''
#* ''android:debuggable="false"'' - this reduce the apk size file from 7M to less than 1M!
# Edit ''res/values/strings.xml'' and change the app name for "Moodle mobile" - this app name appears on your Android phone dashboard. The Google Play Store app name comes from the Google Play publisher console.
# Clean up the app to reduce apk file size
#* ''rm -rf platforms/android/assets/www_old/''
#* ''rm -rf platforms/android/assets/www/img/splash''
#* ''rm -rf platforms/android/assets/www/img/icon''
# In Eclispe, build and test the app.
# In Eclipse, File > Export the app with the Moodle HQ Google Play keystore. Then upload the APK to Google Play.
=== Warnings ===
* if you previously installed a different platform then you'll get an error when adding the cordova plugin. It's advised to install both platforms at the same time. Then add the cordova plugin(s), then copy the app content into www. Don't forget cordova.js and plugin js/files. Then you can manually install phonegap plugins.
= See also =
* [[Moodle Mobile Building the app for iOS]]
* [[Moodle Mobile]]

Moodle Mobile Building the app for iOS

2022-04-29T07:14:10Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle App (Ionic 3)}}

Remember that you can also build the app using an external system called Phonegap Build, see [[Moodle_Mobile_Customization#Building]]

{{obsolete}}

== Mac OSX ==
this is a quick guide to build the official Moodle Mobile app on iOS. It should be pretty easy to do it for your own organization.
# Install xcode
# Install NodeJs
#*http://nodejs.org/
# Install cordova-cli
#* ''sudo xcodebuild -license'' - agree to xcode license
#* ''sudo npm install -g cordova'' - it will install cordova. Note that on my machine I have some warnings about the ios bootstrap process being skipped but all the following steps seem to work ok anyway...
# Create a Xcode project
#* ''/usr/local/lib/node_modules/cordova/bin/cordova create ~/Apps/moodlemobile_android_cordova com.moodle.moodlemobile MoodleMobileBeta''
#* ''cd ~/Apps/moodlemobile_android_cordova''
#* ''sudo /usr/local/lib/node_modules/cordova/bin/cordova platform add ios''
#* ''sudo /usr/local/lib/node_modules/cordova/bin/cordova build'' - not necessary, just check the build works.
# In Finder change the permission on ~/Apps/moodlemobile_android_cordova folder: Read + Write to everyone
# Add the cordova plugins
#* ''git clone git://github.com/alunny/ChildBrowser.git ./ChildBrowser'' - we are now going to install cordova compatible plugin with the plugin install command line.
#* ''sudo /usr/local/lib/node_modules/cordova/bin/cordova plugin add ChildBrowser/''
# In Finder open ''/Users/jerome/Apps/moodlemobile_android_cordova/platforms/ios/MoodleMobileBeta.xcodeproj''. Test you can build the default Cordova app on your phone.
# Copy the Moodle mobile app into www folder
#* ''git clone git://github.com/moodlehq/moodlemobile.git ./moodlemobile''
#* ''mv platforms/ios/www/ platforms/ios/www_old/''
#* ''mv ./moodlemobile/ platforms/ios/www/''
#* ''cp platforms/ios/www_old/cordova.js platforms/ios/www/''
#* ''cp platforms/ios/www_old/childbrowser.js platforms/ios/www/''
#* ''mv platforms/ios/www_old/childbrowser platforms/ios/www/''
# In Xcode, edit ''Resources > MoodleMobileBeta-Info.plist''
#* Bundle display name: ''Moodle'' - "Moodle mobile" would be displayed "Moodl...obile"
#* Bundle version: ''1.2.0.3''
# Add icons and splash
#* ''cp platforms/ios/www/img/icon/ios/icon-57.png platforms/ios/MoodleMobileBeta/Resources/icons/icon.png''
#* ''cp platforms/ios/www/img/icon/ios/icon-57-2x.png platforms/ios/MoodleMobileBeta/Resources/icons/icon@2x.png''
#* ''cp platforms/ios/www/img/icon/ios/icon-72.png platforms/ios/MoodleMobileBeta/Resources/icons/icon-72.png''
#* ''cp platforms/ios/www/img/icon/ios/icon-72-2x.png platforms/ios/MoodleMobileBeta/Resources/icons/icon-72@2x.png''
#* ''cp platforms/ios/www/img/splash/ios/* platforms/ios/MoodleMobileBeta/Resources/splash''
# Go to Targets > Summary
#* check pre-rendered icon
#* enable all orientation
#* Deployment target: 4.3
#* Version: 1.203 Build: 1.2.0.3
#* Check that all icons and all splash-screens are there.
# Clean the app
#* ''rm -rf platforms/ios/www/img/splash''
#* ''rm -rf platforms/ios/www/img/icon''
# Build and publish

=== Warnings ===
* If you previously installed a different platform then you'll get an error when adding the cordova plugin. It's advised to install both platforms at the same time. Then add the cordova plugin(s), then copy the app content into www. Don't forget cordova.js and plugin js/files. Then you can manually install phonegap plugins.
* The iOS version doesn't need WebIntent android plugin.
* You must add the childbrowser cordova plugin just after adding the platform. In Cordova 2.5, if you add the plugin after installing the app content, it creates a folder named childbrowser.js, and the plugin doesn't work.

== See also ==

* [[Moodle Mobile Building the app for Android]]
* [[Moodle Mobile]]
* [http://photokandy.tumblr.com/post/46289610781/getting-started-with-cordova-cli Blog post on how to install cordova-cli]

Moodle Mobile custom apps

2022-04-29T07:14:08Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 2 (Ionic 1)}}
== Overview ==
You will need a custom app if you want:
* Force the users to log in to your site URL
* Custom corporate image (name, app icon, theme, store entry)
* Add additional features or static pages
* Remove or change existing features
* Custom translation of the app
* Use your own notifications infrastructure
== Requirements ==
* Code editor (Sublime, WebStorm, Eclipse, Netbeans...)
* Github account (http://github.com/)
* Github desktop app (http://windows.github.com/)
* PhonegapBuild account
* Chromium browser as described here: [[Moodle Mobile development using Chrome or Chromium]]
== Steps for creating your Custom App ==
=== Setting up your computer ===
Follow these guides:
* [[Setting up your development environment for Moodle Mobile 2]]
* [[Moodle Mobile development using Chrome or Chromium]]
=== Fork the app ===
Use the Fork tool in:
https://github.com/moodlehq/moodleapp (You must be logged with your Github user!)

[[File:forkCustomApp.png]]
=== Clone the repo in your desktop ===
You can use your favourite GIT client (or GitHub Desktop clients)

[[File:clone.png]]
=== Create a new branch ===
Having the code in a separate branch in the forked repository will make very easy to maintain our customizations using git tools (merge, rebase)

[[File:branch.png]]
=== Edit the app settings file ===
'''/config.xml'''
* Change the widget id value (instead com.moodle.moodlemobile your own id)
* Change the app name and description
'''/www/config.json'''
* Change versionname
* Add a pre-fixed URL: Adding a field like “siteurl”: “http://mysite.abc”
* Change gcmpn (if you are using your custom Google Push infrastructure)
* Change the appid (required for making Push notifications work)
* Remove demo sites (“demo_sites”: “”)
=== Edit another app files ===
'''/www/core/component/settings/lang/x.json (x means all the languages)'''
* Change the “appname” string to match your custom app name (Not necessary in latest version Moodle Mobile 3.1.3), you can change it in config.json
'''/www/errorreport.js'''
* Change: var reportUrl to point to your custom error reporting system (if you want to use your custom one)
* Same for appVersion
=== Replace the app icons, splashscreen ===
* Replace the resources/ icon.png and splash images
* Replace also the www/img/moodle.png with an image matching your logo
* '''In a console:'''
** cd mycustomappdir/
** ionic resources
This will create your custom icon and splash images in all the required sizes

More information about Ionic’s image generation: http://ionicframework.com/docs/cli/icon-splashscreen.html
=== Add your custom styles ===
* Add your custom styles in scss/app.scss
* Sample theme available at: [[Moodle Mobile Themes]]
[[File:addCustomStyle.png]]
== Building your Custom App ==
There are two options for building the app:
* Ionic CLI
** Local building (require installation of Android and iOs SDK and emulators)
** See http://ionicframework.com/docs/cli/run.html
* Phonegap Build
** Remote building (cloud service)
** This is the recommended way because it doesn’t require to install all the SDK, emulators (or having to buy a Mac for developing)
=== Building with Phonegap Build ===
==== GitHub ====
* First of all, you need to create a new repository in GitHub. This is because Phonegap Build requires a different directory structure than Ionic CLI and we need a branch per platform.
* In your forked repository, run ''gulp'' so the build files are updated.
* Copy all the code inside the www/ in your forked repository directory to this new repo/branch.
* Also copy the /resources directory from the ionic project to a new /resources directory in the phonegap build repository
* You also have to place the /resources/icon.png and /resources/splash.png you used to create your resource files in the root folder in the phonegap build repository
* Use this repository as an example: <s>github.com/moodlehq/moodlemobile-phonegapbuild/tree/learn-moodle</s>
* In the Phonegap Build repo root folder you need to add a special config.xml file (different to the Ionic one), use [https://raw.githubusercontent.com/moodlehq/moodlemobile-phonegapbuild/learn-moodle/config.xml this file] as a template. Please, replace there the app name, versions, etc.
* Then, in the Phonegap build repo you need two create two additional branches based on master: android and ios
* In the android and ios branch you need to apply these changes:
Disable debugging in the app:

[[file:disableDebug.png]]

Add android or ios base class (so the app use native style widgets):

[[file:addBaseClass.png]]
* The rest of the commits can be safely omitted:
** Add reporting library
** Add official tag
==== Phonegap ====
* Create an account in ''PhoneGap''.
* For iOS you need to create certificates/provisioning files.
* For Android, you can download and install the .apk for testing, for production follow the previous guide.
* In order to build, add your repository https link and also the branch in the Phonegap Build settings (you will have to do two different builds: one for the android branch and another one for the ios branch)
* In order to update your app for phonegap build you have to (this will apply all the specific android/ios commits to your master branch):
** Upload new versions of the app to the www/ directory and then execute the commands:
** git rebase master android
** git push -f
** git rebase master ios
** git push -f
=== Remove existing features ===
* You can only remove add-ons.
* In order to disable an add-on you need to delete the folder.
* Add-ons are located in the www/addons folder.
* In case you want to remove a particular functionality of an add-on you will need to edit the files inside the addon. Please notice that removing a state is not enough for a feature to be disabled, you also need to remove all the links to that state to prevent errors.
* Then run gulp or ionic serve in the project root folder so the build files are created.
=== Change the app strings ===
* Language strings are located in:
** www/core/lang folder (a different file for each language)
** www/core/components/COMPONENT_NAME/lang folder
** www/addons/ADDON_NAME/lang folder
* Language files are .json files, you can edit it using a text editor. Please, use jsonlint.com to validate that the new language file is correct.
* Then run '''gulp''' or '''ionic serve''' in the project root folder so the build files are created
=== Change the initial screen (add site) ===
* To make the app use a fixed site URL you need to add a new setting in the config.json file: “siteurl”: “http://yourmoodle.com”
* Then run '''gulp''' or '''ionic serve''' in the project root folder so the build files are created.
You can see an example from our Learn Moodle app (that is a custom version of Moodle Mobile) here: https://github.com/jleyva/moodleapp/blob/learn-moodle/www/config.json
=== Keep your custom version up2date ===
* Sync your fork: https://help.github.com/articles/syncing-a-fork/
* Rebase your changes (and resolve conflicts):
** git rebase master yourcustombranch
* Upgrade your version number
* Commit your changes
* Apply the changes in your Phonegap Build specific repository
* Rebuild with Phonegap build for both android and ios branches
* Publish in the store

Moodle Mobile Development Process

2022-04-29T07:14:06Z

Pferre22:

{{Template:WillNotMigrate}}
{{Warning|This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.}}

== Versions ==

Moodle Mobile version numbers consist of three numbers separated by a dot, for example 1.3.2 or 1.4.4. The first two numbers, like 1.3, represent the major version. The third number distinguishes minor versions within the same major version.

=== Major and minor versions ===

* Major version includes new features and improvements.

* Minor version includes only bug fixes.

The current release cycle is one version per month (in the first two weeks of every month)

== See also ==

[[Moodle Mobile Release Notes]]

[[Category: Mobile]] [[Category: Obsolete]]

Moodle Mobile Testing with Phonegap Developer app

2022-04-29T07:14:02Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 1}}
''Phonegap Build'' service was discontinued October, 1 2020.
The ''Phonegap Developer app'' is a tool that allow developing locally and see the changes instantly on your mobile device.

It's not a tool that can be used for developing and testing all the features of the Moodle Mobile app since it doesn't support all the plugins used by the app and also, the FileTransfer plugin are not fully supported.

It doesn't support also connection to different sites using XHR (Ajax) request using POST or HEAD methods.

The app is suitable for testing mainly CSS / Design issues in different devices (iOs, Android and WindowsPhone 8)

If you want to test the Moodle Mobile app in order to polish design issues, please follow this instructions:
* Install the Phonegap Developer app in your iOs, Android or WindowsPhone 8 device
* Install node.js http://nodejs.org/
* In a terminal/console: sudo npm install -g phonegap
* Terminal/console: cd directory_where_to_create_the_project
* Terminal/console: phonegap create moodlemobile
* Terminal/console: cd moodlemobile
* Delete the contents of the www/ folder
* Copy the Moodle Mobile app files into the www/ folder
* In a terminal, cd to the project folder and then: phonegap serve (This will launch a local server, you can stop the server doing a ctrl+c)
* Open the app in a device, and copy the server Address that the previous command displayed
* In the Moodle Mobile app Site URL field enter: mmtest (It's a "fake" test site, remember that you can't connect to real sites using the Phonegap Developer app)
Remember that every time you want to use the Phonegap Developer app, you need to open a terminal/console, cd to your phonegap project folder, and run the command:
phonegap serve
If you have problems testing with the app, try to close the app in your Mobile device and stop the Phonegap server (ctrl + c in the terminal)
[[Category: Mobile]]

Setting up your development environment for Moodle Mobile 2 (Ionic 1)

2022-04-29T07:13:59Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 2 (Ionic 1)}}

IMPORTANT: This documentation will be obsolete in May 2018, please [https://moodle.org/mod/forum/discuss.php?d=360412 read this announcement].

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

== Requirements ==

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

http://nodejs.org

For Mac users we recommend to install NodeJS via Macports.

Node 6.9.1 has been verified to work fine with the app. If you're having problems with later versions you might want to check if it works with 6.9.1.

"note": if you also need later versions of node for other projects, use Node Version Manager aka "nvm" [https://github.com/creationix/nvm here]. Linux and OSX is supported, and the site has pointers to windows alternatives. Simply type:
nvm install 6.9.1
nvm use 6.9.1

'''Install ionic:'''
npm cache clean
npm install -g cordova@6.5.0 ionic@2.2.3 # (If it throws an EACCESS error, run it again with sudo)

Please notice that Ionic 2.2.3 is being used. The CLI for Ionic 3 breaks our building system, there is an open issue to fix this: [https://tracker.moodle.org/browse/MOBILE-2112 MOBILE-2112].

'''Install the npm required packages'''
sudo npm install -g bower # (This will install bower in a folder that should be in the PATH)
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

'''Push notifications for Mac'''

Phonegap plugin push 1.9.0 requires CocoaPods to work. The installation steps can be found in https://cocoapods.org/

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

'''Clone the code base into a local directory in your computer.'''
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory

== Automatically setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json file 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

This command will throw some warnings, since Ionic 1 requires some libraries that are deprecated. Just ignore all the npm WARN messages.

If this instruction is successful you can jump to the section [[#Open_the_app_in_the_browser|Open the app in the browser]]. If it fails, please check the next section.

== Manually setup the environment ==

'''Install the npm plugins dependencies'''

npm install (This will install all the dependencies listed in package.json)

This command will throw some warnings, since Ionic 1 requires some libraries that are deprecated. Just ignore all the npm WARN messages.

'''Add the iOS and Android platforms and install the required Cordova plugins'''

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /config.xml file 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].

Run the following command to install the platforms and all the required Cordova plugins:
cordova prepare

Cordova Android 6.1.2 and Cordova iOS 4.3.1 have been verified to work fine with the app. If you're having problems with later versions you might want to check if it works with these versions.

'''Install javascript libraries'''
bower install (this will install all the libraries listed in bower.json)

'''Run gulp’s default tasks (in order to create the build files)'''
gulp

== 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]]

and then, start the Ionic server:

ionic serve --browser chromium

If you don't want to open any browser you should run:

ionic serve -b

== Editor ==

There are several plugins for AngularJS and Ionic development available for common editors.

Sublime 3 has plugins for [https://github.com/SublimeLinter/SublimeLinter-jscs jscs] (coding style) and [https://github.com/SublimeLinter/SublimeLinter-jshint jshint] (linter)

Configuration files for jscs and jshint can be downloaded from https://github.com/angular/angular.js (.jscs.json and .jshint*)

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic platform remove android
ionic platform remove ios
ionic platform add android
ionic platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see this guide to be able to build for Android and iOS using the command line:

http://cordova.apache.org/docs/en/5.0.0/guide_platforms_index.md.html#Platform%20Guides

'''Common errors when building'''

* com.android.dex.DexException: Multiple dex files define XXX
Open the file ''platforms/android/build.gradle'' and add these 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.

== Troubleshooting ==

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

== See also ==

http://ionicframework.com/docs/cli/

Upgrading Airnotifier

2022-04-29T07:12:50Z

Pferre22:

{{Template:WillNotMigrate}}
{{Warning|This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.}}

Steps to upgrade

* Stop the server, killing the process
<syntaxhighlight lang="php">
ps aux | grep airnotifier
kill -9 PROCESS_ID
</syntaxhighlight>

* Backup the MongoDB databases
*# Backup AirNotifier settings database <br/><syntaxhighlight lang="php">mongodump -h localhost --port 27017 -d airnotifier -o /var/airnotifier/</syntaxhighlight>
*# Backup each application data<br/><syntaxhighlight lang="php">mongodump -h localhost --port 27017 -d commoodlemoodlemobile -o /var/airnotifier/;</syntaxhighlight><br/><syntaxhighlight lang="php">mongodump -h localhost --port 27017 -d commoodlemoodlemobiletest -o /var/airnotifier/</syntaxhighlight>

* Pull latest version from git
<syntaxhighlight lang="php">
cd /opt/airnotifier
git pull
</syntaxhighlight>

* Check that your current version has a version number in the options collection (AirNotifier settings database) (Older AirNotifier versions doesn't have it), use the shell:
mongo
use airnotifier
db.options.find()

* If there is not a value option, create a new one:
db.options.insert({name: "version", value: 20140101})

* Run the upgrade.py script
cd /opt/airnotifier
python upgrade.py

* Start the server again
./startserver
or
sudo -u airnotifier python airnotifier.py >> /var/airnotifier/console_log 2>> /var/airnotifier/error_log &

[[Category: Mobile]] [[Category: Obsolete]]

Moodle Mobile 1 Developing a plugin tutorial part 2

2022-04-29T07:09:26Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 1}}

== Introduction ==

In the second part of this tutorial we are going to add new WebServices inside our custommm local plugin.

The new WebServices will let us to add a new "forums" plugin to or custom MoodleMobile app.

== Plugin spec ==

We want to develop a "forums" plugin that will display all the forums an user it's available to see inside a course.
We will be able to read discussions and post (only read, not write)

A screenshot of the desired result:

[[File:forums.png]]

== Steps ==

=== Add the new WebServices in the local plugin ===

You cand find here the plugin with the forum WebServices added, https://github.com/cvaconsulting/moodle-local_custommm

When adding new WebServices to a plugin, don't forget to update the services file and also bump the version number.

Update the plugin in your installation as an usual plugin upgrade process.

=== Add the new WebServices to your custommm service ===

In your Moodle installation, you need to go to Admin -> Plugins -> WebServices -> Services, edit the custommm service for adding the new forums WebServices

=== Set up your MoodleMobile client ===

Edit the config.json file, and add "forums" in the plugins setting

"plugins" : ["notifications", "upload", "contents", "participants", "addcontact", "addnote", "sendmessage", "groups", "forums"],

=== Develop the MoodleMobile plugin ===

The full source code can be found here:

https://github.com/cvaconsulting/moodlemobile-forums

[[Category: Mobile]]

Moodle Mobile 1 Plugins Development

2022-04-29T07:09:23Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 1}}

=== Overview ===

Plugins allow developers to extend the app functionalities.
A plugin is a subdirectory that implements a set of required functionalities.

IMPORTANT: Plugins are not automatically loaded, you must indicate the plugins to be loaded in the config.json file (plugins option).

IMPORTANT: Read carefully this document ([[Moodle Mobile 1 Customization]]) before you start developing!

You can view a step by step guide of how to create a plugin in this presentation [http://es.slideshare.net/juanleyva/creating-a-custom-moodle-mobile-app-moodle-moot-spain-2014 Creating a custom Moodle Mobile app - MoodleMoot Spain 2014]

=== Types of plugins ===

* General: Interactions over the global app, such as the Notifications, Upload, Help and Web
* Course: Interactions over a course, such as course contents or participants
* User: Interactions over an user, such as send a message, add as a contact, write a private note
* Settings: Additional settings for the app

=== Structure of a plugin ===

We are going to use this plugin: https://github.com/moodlehq/moodlemobile/tree/master/plugins/participants as an example:

Plugins have always the same structure (no matter the type of plugin), the app uses a Register App where you declare a Plugin and then register it to the App.

A plugin must be a directory under the plugins/ dir containing:

* A main.js file, where the plugin is declared
* Templates html files (if used)

====Defining a plugin====

<syntaxhighlight lang="javascript">
var templates = [
"root/lib/text!root/plugins/participants/participants.html",
"root/lib/text!root/plugins/participants/participant.html"
];

define(templates,function (participantsTpl, participantTpl) {
</syntaxhighlight>

For loading plugins we use the RequireJS library, a plugin is a module that we must define using the lines above:

We define a new module that depends on the html files (templates) listed above, once loaded, the contents of the HTML files will be available in the participantsTpl and participantTpl variables.

Notice that the app doesn't automatically load the plugins, you need to edit the config.json file for indicating the plugins to be loaded

"plugins" : ["notifications", "upload", "contents", "participants", "addcontact", "addnote", "sendmessage", "yourpluginname"],

====Global settings of the plugin====

<syntaxhighlight lang="javascript">
settings: {
name: "participants",
type: "course",
menuURL: "#participants/",
lang: {
component: "moodle"
}
},
</syntaxhighlight>

The name of the plugin (must be the same that the directory name)

The type of plugin (general, course, user, settings)

The main link to the plugin in the App

The language file to use, here we are using moodle because we are using the main language file, for plugins, you should use the Moodle franken-style plugin name where the lang file is located in your Moodle installation i.e: "local_mycustomplugin"

This means that you need to put your language files in a local plugin (called mycustomplugin) in your Moodle installation, this local plugin should be the same where you are going to add your custom Web Services

Example settings for custom plugins:

<syntaxhighlight lang="javascript">
settings: {
name: "mycustomplugin",
type: "general",
menuURL: "#custom/",
lang: {
component: "local_mycustomplugin",
strings: {
"stringid1": "string contents",
"stringid2": "string contents 2"
}
}
},
</syntaxhighlight>

Notice that the lang.strings property is needed because until we sync to the remote Moodle installation for downloading the language pack, we are going to need this temporal strings.

You can also can add the strings in a json file and uses the same method that for loading templates (add the lang json file as a dependency and then assign to the lang.strings property the variable returned by the define function, see above)

====Storage====
<syntaxhighlight lang="javascript">
storage: {
participant: {type: "model"},
participants: {type: "collection", model: "participant"}
},
</syntaxhighlight>

Here we declare the "tables" and their "structure"

If you are not familiar with Models, you must think that participants is a table that contains the participant's records.

Notice that we are not indicating the "fields" of the "tables" this is not necessary.

====Routes====
<syntaxhighlight lang="javascript">
routes: [
["participants/:courseId", "participants", "showParticipants"],
["participant/:courseId/:userId", "participants", "showParticipant"],
],
</syntaxhighlight>

For avoid binding DOM elements to functions, we use a Route navigation model, any time an user clicks on a button or link, the hash part of the URL is changed and the function linked to the hash part is triggered.
So, if you want to trigger the function ShowParticipant, you must create a button or link that points to "#participant/courseid/userid", when the user click on the link the function showParticipant(courseid, userid) is triggered
One of the advantages of using roues, is that we preserve the browser history so the "back" button on an Android device will work as expected without any extra code.

'''Sync, aka cron or periodic tasks'''
<syntaxhighlight lang="javascript">
sync: {
handler: MM.plugins.myplugin.functionName,
time: 60
},
</syntaxhighlight>

You can hook to the sync/cron/periodic tasks core subsystem, just create a property called Sync with two sub-properties:

* handler: The function that is going to be executed
* time: The execution interval

The sync subsystem is used for synchronize language strings and also for sending operations performed when offline.

====Functions====
<syntaxhighlight lang="javascript">

showParticipants: function(courseId) {
MM.panels.showLoading('center');

if (MM.deviceType == "tablet") {
MM.panels.showLoading('right');
}

var data = {
"courseid" : courseId
};

MM.moodleWSCall('moodle_user_get_users_by_courseid', data, function(users) {
var tpl = {users: users, deviceType: MM.deviceType, courseId: courseId};
var html = MM.tpl.render(MM.plugins.participants.templates.participants.html, tpl);
MM.panels.show('center', html);
// Load the first user
if (MM.deviceType == "tablet" && users.length > 0) {
MM.plugins.participants.showParticipant(courseId, users.shift().id);
}
});
},

showParticipant: function(courseId, userId) {
var data = {
"userlist[0][userid]": userId,
"userlist[0][courseid]": courseId
}
MM.moodleWSCall('moodle_user_get_course_participants_by_id', data, function(users) {
// Load the active user plugins.

var userPlugins = [];
for (var el in MM.plugins) {
var plugin = MM.plugins[el];
if (plugin.settings.type == "user") {
userPlugins.push(plugin.settings);
}
}

var tpl = {"user": users.shift(), "plugins": userPlugins, "courseid": courseId};
var html = MM.tpl.render(MM.plugins.participants.templates.participant.html, tpl);
MM.panels.show('right', html);
});
},

</syntaxhighlight>

Here are the main plugin functions, as you can see we create a function for any single route defined.

As you can see, you don't need much code:

The showParticipants function does the following:

* Shows a loading icon in the center panel

* If we are using a tablet, an additional loading icon is displayed in the right panel

* Then we call a Moodle Web service, using the MM.moodleWSCall function, indicating the name of the WS, the parameters, an a callback function.

* We can add an extra parameter, indicating that this function perform write actions in the server, see: https://github.com/moodlehq/moodlemobile/blob/master/plugins/addnote/main.js#L36

* When the Web service returns info, the next step is to render a Template using the app template function and then display the template in the center panel.

Notice that for referencing the template, we use the MM global object: MM.plugins.participants.templates.participants.html (MM . registered plugins . name of the plugin . property . template name . contents of the template

* If we are using a tablet, we load in the right panel the first participant calling the showParticipant function

Notice that for referencing the function, we use the MM global object: M.plugins.participants.showParticipant

====Templates====
<syntaxhighlight lang="javascript">
templates: {
"participant": {
model: "participant",
html: participantTpl
},
"participants": {
html: participantsTpl
}
}
</syntaxhighlight>

Here we declare the templates we are going to use for further references.

Notice that the attribute html cointains the HTML template files contents (as mentioned above).

====Register the plugin====
<syntaxhighlight lang="javascript">
MM.registerPlugin(plugin);
</syntaxhighlight>

With this single line we register the plugin in the global Namespace MM (the main library of the app)

Notice that registering a plugin is NOT mandatory, so you can have plugins doesn't registered in the app. See "Use cases for plugins" section for more info.

== Use cases for plugins ==

=== Override API functions ===

Since plugins are loaded before the app starts and after the global MM object is loaded, you can overwrite at any time global functions.

So before the Plugin registring you can do thinks like

<syntaxhighlight lang="javascript">

MM.log = function(info) {
// Here goes the code for my custom log function that overrides the default functionality
}

MM.registerPlugin(plugin);
</syntaxhighlight>

=== Load a custom CSS stylesheet ===

<syntaxhighlight lang="javascript">

$('head').append('<link rel="stylesheet" href="plugins/myplugin/mycss.css" type="text/css" />');

MM.registerPlugin(plugin);
</syntaxhighlight>

=== Change the main layout of the app ===

In this case we change the Add Site screen.

<syntaxhighlight lang="javascript">

var templates = [
"root/lib/text!root/plugins/myplugin/tpl.html",
"root/lib/text!root/plugins/myplugin/addsite.html"
];

define(templates,function (baseTpl, myAddSiteCustomTpl) {

[..]

$('#add-site_template').html(myAddSiteCustomTpl);

MM.registerPlugin(plugin);
</syntaxhighlight>

=== Load extra base languages ===

<syntaxhighlight lang="javascript">

var templates = [
"root/lib/text!root/plugins/myplugin/lang1.json",
"root/lib/text!root/plugins/myplugin/lang2.json"
];

define(templates,function (lang1, lang2) {

[..]

MM.loadLang('core', 'es', JSON.parse(lang1.json));
MM.loadLang('core', 'cat', JSON.parse(lang2.json));

MM.registerPlugin(plugin);
</syntaxhighlight>

In all the cases, you can omit to register the Plugin if it doesn't fit in a standard one.

== Moodle Mobile (MM) API ==

Most of the MM APIs are wrappers for other libraries like Backbone.

=== DB/Storage functions ===

====Getting an element from storage by id====

MM.db.get(collection, id);

====Getting elements from storage using conditions====

MM.db.where(collection, {name: value});

Sample code:

<syntaxhighlight lang="javascript">
var notificationsFilter = MM.db.where("notifications", {siteid: MM.config.current_site.id});
</syntaxhighlight>

====Adding a Model to a Collection (inserting an element into a table)====

MM.db.insert(collection, {id: xx, name: yy, value: zz})

MM.db.insert(collection, {name: yy, value: zz}) (This will create a random Unique id)

====Deleting a Modelfrom a Collection by id====

MM.db.delete(collection, modelId);

====Iterate over all the Models of a Collection====

MM.db.each(collection, function(model) { // stuff here});

Sample code:

<syntaxhighlight lang="javascript">
MM.db.each("sync", function(sync){
sync = sync.toJSON();
MM.log("Execugin WS sync operation:" + JSON.stringify(sync.syncData) + "url:" + sync.url);
MM.moodleWSCall(sync.data.wsfunction, sync.data, function(d) {
MM.log("Execugin WS sync operation FINISHED:" + sync.data.wsfunction);
MM.db.delete("sync", sync.id);
}, {cache: 0});
});
</syntaxhighlight>

=== Internationalization functions ===

====Getting a translated string====

MM.lang.s("string_id");

Sample code:

<syntaxhighlight lang="javascript">
MM.lang.s("therearenotnotificationsyet");
</syntaxhighlight>

=== Templating functions ===

====Render a template====

MM.tpl.render(html, elements);

Sample code:

<syntaxhighlight lang="javascript">
var tpl = {users: users, deviceType: MM.deviceType, courseId: courseId};
var html = MM.tpl.render(MM.plugins.participants.templates.participants.html, tpl);
</syntaxhighlight>

Template:

<syntaxhighlight lang="html4strict">
<section class="users-index-list">
<form class="search">
<input type="search" results="5" placeholder="Search...">
</form>
<ul class="nav nav-v">
<% _.each(users, function(user) { %>
<li class="nav-item">
<a href="#participant/<%= courseId %>/<%= user.id %>" class="media">
<div class="img">
<img width="35" src="<%= MM.fixPluginfile(user.profileimageurlsmall) %>" alt="img">
</div>
<div class="bd">
<h3><%= user.fullname %></h3>
</div>
</a>
</li>
<% }); %>
</ul>
</section>
</syntaxhighlight>

=== Message popups/dialogs===

MM.popMessage(text, options);

MM.popErrorMessage(text, options);

=== Device ===

MM.deviceType (returns phone or tablet)

MM.deviceConnected() (returns true or false if the device has Internet access)

For a tutorial about developing plugins for Moodle Mobile see: [[Moodle Mobile 1 Developing a plugin tutorial]]

== See also ==

[http://es.slideshare.net/juanleyva/creating-a-custom-moodle-mobile-app-moodle-moot-spain-2014 Creating a custom Moodle Mobile app - MoodleMoot Spain 2014]
JsDoc Reference http://moodlehq.github.com/moodlemobile/

Moodle Mobile 1 simulator

2022-04-29T07:09:21Z

Pferre22:

{{Template:WillNotMigrate}}
The Moodle Mobile 1 Simulator (MMS) https://github.com/jleyva/moodlemobile-simulator is a tool to make easier developing for Moodle Mobile, it includes options for simulate Push notifications, watch and filter the app log, browse the "sandboxed" Chromium file system etc...
{{obsolete}}
{{Moodle Mobile 1}}

[[{{ns:file}}:moodlemobilesimulator.png|thumb|300px]]

== Features ==

* It can emulate different devices/platforms viewport size (iPhone, iPad, Nexus4...)
* You can switch between different versions of the app and between different Test Sites
* It support emulation of "Offline" mode
* It cam simulate injection of Mobile themes (Mobile CSS URL)
* Rotate device
* Disable support of the local_mobile plugin for sites using that plugin
* Live CSS injection and template modifications for quick testing
* Emulation of Push notifications with configurable payload
* Support the Phonegap FileSystem and FileTransfer API so you can download/upload and store files in the Chromium filesystem
* Support additional app options like taking photos (using the webcam) an uploading audio recording

== Installation ==

* First of all you need to configure Chrome or Chromium as described here [[Moodle_Mobile_development_using_Chrome_or_Chromium]]

* Download the project from github: https://github.com/jleyva/moodlemobile-simulator

* Open the index.html in the Chrome/Chromium browser (you don't need to install the simulator in a local server, you can just open the file in the browser doing a File -> Open)

* In Settings Apps, add a new App pointing to the directory where your HTML code is placed

* You can also add Apps and Sites in the config.json file (elements added here can be deleted using the GUI, you should delete it directly from the JSON file)

* Go to Launch, select your App and device (optionally a Site) and "Launch app" Once logged in a site, it will require you to allow use the local file system storage capabilities

Moodle Mobile 1 Themes

2022-04-29T07:09:19Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 1}}

The Mobile app can retrieve your custom styles from your Moodle site. Since is an HTML5 app, you can apply safely CSS3 styles.

In your Moodle installation go to Plugins / Web services / Mobile and enter in the mobilecssurl field a valid URL pointing to a CSS file containing your custom styles (theme).

The CSS should be placed inside your Moodle installation (in your custom theme or inside a local plugin)

Once the user is logged in the app, there is a periodical process that retrieves your remote CSS files for applying your custom styles into the app.

Notice that on the first time a user opens the app, he will see the default "orange" style. Your custom styles will be applied once the user has added a site in the app.

Notice also that styles comes from a site, there is no way for changing the Add site / Manage account styles.

== Elements and properties that can be styled ==

The images below show the elements and properties that can be styled.

[[File:styleable_elements.png]]

The page title that is visible only on mobile at the moment.

[[File:styleable_elements_mobile.png]]

== How to modify the app icons ==

There are several ways for modifying the app icons

All the parent elements of img tags containing app icons has a "app-ico" class applied, so it's very easy to modify icons using styles

=== Use CSS filters ===

<pre>
.app-ico img {
-webkit-filter: invert(100%);
}
</pre>

This will make all the icons black

More information about filters: http://www.html5rocks.com/en/tutorials/filters/understanding-css/

=== Replace images using CSS ===

<pre>
img[src*="notifications/icon.png"] {
content: url(dataURI);
}
</pre>

Notice that for allowing the app works offline, images hosted in remotes servers should not be referenced. Instead, data URIs should be used. Note also that this makes the CSS file bigger.

More information about data URIs http://css-tricks.com/data-uris/

== Testing ==

You can use the [[Moodle Mobile simulator]] for testing your CSS file, it includes an option for simulating the Mobile CSS URL Moodle feature.

Also, you can use Safari or Google Chrome developer tools for debugging and changing the CSS styles in live:

https://developer.chrome.com/devtools/docs/remote-debugging

http://phonegap-tips.com/articles/debugging-ios-phonegap-apps-with-safaris-web-inspector.html

== Example of a custom theme (CSS file) ==

Notice that the data URI for the image is shorten, you can view the complete example here: https://gist.githubusercontent.com/jleyva/0821122c3461925b45a7/raw/425821513072daf7ce5a16874f3ea21ffe92325e/moodlemobile-sample_theme.css

<pre>
body {
color: #666666; /*default*/
background: #4bcaff;
}
a {
color: #0088cc; /*default*/
}
h1 {
color: #4bcaff;
}
h2 {
color: #ffffff;
text-shadow: 0px 1px 1px rgba(0, 0, 0, 0.2); /*default*/
background-color: #7a8a94;
}
.nav .nav-item a {
color: #666666; /*default*/
}
#manage-accounts .account-details {
color: #666666; /*default*/
}
.header-wrapper {
box-shadow: 10px 0 20px rgba(0, 0, 0, 0.3); /*default*/
}
.header-main {
color: #4b565d;
background: #4bcaff;
}
#page-title {
text-shadow: none;
}
#panel-right,
#panel-center {
background: #ffffff; /*default*/
}
.user-menu {
background: #4bcaff;
}
.user-menu header {
background: #4b565d url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAU***);
border-bottom: 5px solid #ffffff;
box-shadow: 10px 0 20px rgba(0, 0, 0, 0.3);
}
.user-menu header h1 {
color: #ffffff; /*default*/
text-shadow: 0px 1px 1px rgba(0, 0, 0, 0.2); /*default*/
}
.user-menu h2 {
color: #4b565d;
text-shadow: 0px 1px 1px rgba(0, 0, 0, 0.2); /*default*/
background: #ffffff;
box-shadow: none;
}
.user-menu .nav-item > a {
color: #4b565d;
text-shadow: 0px 1px 1px rgba(0, 0, 0, 0.2); /*default*/
}
.user-menu .nav-item .plugin-ico,
.user-menu .nav-item .course-ico {
background-color: #4b565d;
}
.grades .section-name {
color: #ffffff;
text-shadow: 0px 1px 1px rgba(0, 0, 0, 0.2); /*default*/
background-color: #7a8a94;
border-bottom: 1px solid #ffffff; /*default*/
}
</pre>

== See also ==

http://caniuse.com/ Support tables for CSS3 styles (including Mobile browsers)

[[Category: Mobile]]

Moodle Mobile 2 (Ionic 1)

2022-04-29T07:09:16Z

Pferre22:

{{Template:WillNotMigrate}}
<p class="note">For user documentation see '''[[:en:Moodle Mobile|Moodle Mobile]]'''.</p>
{{Moodle Mobile 2 (Ionic 1)}}

IMPORTANT: This documentation will be obsolete in May 2018, please [https://moodle.org/mod/forum/discuss.php?d=360412 read this announcement].

== General Overview ==

Moodle Mobile 2 (MM2) is the official mobile app for Moodle. MM2 is an HTML5 app that uses the Ionic hybrid apps framework. Former Moodle Mobile versions (1.x) used jQuery and Backbone (see [[Moodle Mobile 1]] for documentation about the former app).

Basically, the app is a Web Services client that uses REST as protocol to obtain and send information to your Moodle installation/s.

Interaction with the phone and compiling/packaging is done using the Cordova framework (also commonly known as Phonegap).

MM1 plugins are not going to work in MM2.

== Requirements ==

* Moodle 2.4
* Mobile services enabled (Administration -> Plugins -> Web Services -> Mobile)

Future versions will require the last minor versions if Web Services are not back ported.

== Architecture ==

MM2 is built with ionic framework, ionic is a full stack mobile hybrid apps that uses AngularJS framework.

AngularJS is a structural framework for dynamic web apps. It lets you use HTML as your template language and lets you extend HTML's syntax to express your application's components clearly and succinctly.

AngularJS is quite popular, you may find lot of sites with updated documentation and free courses, the same applies for Ionic.

=== Ionic / AngularJS ===

The app architecture is the typical for an AngularJS app. We use controllers, factories, directives, providers, etc..

The app is designed in a modular way, most of the functionalities are AngularJs modules that implements plugins (in a similar way to Moodle plugins).

There are a set of core services for handling authentication, configuration, plugin management, cache, etc… and specific modules for tasks like internationalization.

Most of the services are implemented as factories.

The app uses AngularJs logging to create an application log (only in developer mode).

=== App structure and naming conventions ===

The app is structured in two parts: core and addons.

In core we have the code that the app needs to be able to work (basic version). There are services, components, directives, filters, etc.

The components inside core are similar to addons, but the app needs them to work: login, sidemenu, courses, etc. Each component needs to define a main.js file to initialize it and to define the module.

Naming conventions for core:
* The module name for components needs to be mm.core.componentname and it should be defined in the component’s main.js. The services, filters and directives that don’t belong to a component need to use the module mm.core (defined in www/core/main.js).
* All the services names need to start with $mm, followed by the service name in camel-case. For example, $mmSitesManager.
* The filters and directives use camel-case starting with mm. For example, mmFormatText.
* The controllers names need to start with mm (without dollar), followed by the controller name in camel-case. The controller name needs to contain Ctrl to easily identify it as a controller. For example, mmCourseListCtrl.

In addons we have the official MM2 addons. Each addon can have services, controllers, templates, directives, filters, styles and lang files. The addon needs to specify a main.js file to initialize the addon and to register itself into one or more delegates (this determines where will the plugin be shown).

Naming conventions for addons:
* The module name for addons needs to be mm.addons.addonname and it should be defined in the addon's main.js.
* All the services names inside an addon need to start with $mma, followed by the addon name and the service name in camel-case. For example, $mmaMessagesHandlers.
* The filters and directives inside an addon use camel-case starting with mma followed by the addon name and the directive/filter name. For example, mmaMessagesFormat.
* The controllers names need to start with mma (without dollar), followed by the addon name and the controller name in camel-case. The controller name needs to contain Ctrl to easily identify it as a controller. For example, mmaForumListCtrl.

Naming conventions for subaddons:

Subaddons match Moodle subplugins or subsystems (like question behaviours, question types or quiz access rules).
* The module name for subaddons needs to be mm.addons.addonname_subaddonname and it should be defined in the addon's main.js.
* The rest of the conventions are the same that for addons but adding the subaddon name to the addon name. See www/addons/qtype or www/addons/qbehaviour for examples

=== Internationalization ===

The app is translated to several languages, we use a module called angular-translate that supports lazy-loading of languages and pluralization. All the languages files are shipped with the app except the ones for remote addons.

To load the language files we use angular-translate-loader-partial, a loader developed by angular-translate authors that lets you load “parts” of the translation table. In MM 2.0 we’ll only have a single language file under www/build/lang, but with this loader we should be able to add remote plugins lang files too when they are implemented.

Each plugin/component needs to define its own lang files if they need any. These files need to be placed inside a lang folder and must be named ''languagecode.json'', where ''languagecode'' is the ISO code of the language (i.e. ''en.json''). The structure of those files must be the following:

{
“langkey””: “The string to be shown”
}

All the lang files are merged into a single lang file per language inside www/build/lang. In this merge process, the strings are prefixed to prevent naming collisions. The prefixes are:

* Core strings (www/core/lang): mm.core.*
* Component strings (www/core/components/mycomponent/lang): mm.mycomponent.*
* Addons strings (www/addons/myaddon/lang): mma.myaddon.*

For example, if the example lang file from above was inside the folder www/core/courses/component/lang, the merged file would have an entry like this:

“mm.courses.langkey”: “The string to be shown”

To use the language string, the prefixed version must be used. For example, to use the langkey string from the courses component we need to do this:

$translate('mm.courses.langkey’) - Returns a Promise
<nowiki>{{ 'mm.courses.langkey’ | translate}}</nowiki> - Used in a view, shows the translated string.

Angular-translate is initialized inside www/core/lib/lang.js, where we set English as the fallback language and we load the current language based on the user app settings and the device locale. Notice that locales like “en-uk” or “es-mx” will be treated as “en” or “es” if that translation is not found.

=== Storage ===

The app needs to store some information in the mobile device: the current site information, the list of recorded sites, a cache of the REST calls, etc…

For app storage we use the ydn-db javascript library, it supports storage in IndexedDB, WebSQL and localStorage implementing polyfills, promises, automatic storage system detection, etc...

We have two levels of databases: the app database (1 DB for the whole app) and the site databases (1 DB per site). All the data that is site-related is stored in the site database, so it’s easier to retrieve and delete (when a site is deleted).

The app DB is defined inside www/core/lib/app.js. This file implements a provider with the functions $mmAppProvider.registerStore and $mmAppProvider.registerStores to add new stores to the app DB.

The site DB is defined inside www/core/lib/sitesfactory.js. This factory manages the creation and delete of the sites DB, creating a DB per site.

'''IMPORTANT''': Modifying the schema of an already existing store deletes all its data in WebSQL Storage (in IndexedDB the data is kept). If a store schema needs to be modified, the data should be manually migrated to the new store.

=== Styles ===

'''./scss/app.scss'''
The main SCSS file which a themer should be using to customise the look and feel of the app. That will also be the file we start from to make colour palettes. As core developers we will use this app to override the core ionic variables, as well as modifying existing ionic styles.

'''./www/core/scss'''
This directory holds the styling components we want to offer to our themers. The variables associated with those components should be held in the same files and flagged as !default to allow themers to override them. We should not override those variables in ./scss/app.scss because default values should be provided by us and work with our core app style.

'''./www/core/components/X/scss & ./www/core/addons/X/scss'''
Those directories will contain styles that are specific and should not be re-use by other components/addons. The same goes with the variables from those addons, they should not be re-used from another component/addon.

To prevent naming collisions between SCSS files, the classes and IDs should be prefixed. The naming conventions for those prefixes are similar to the rest of Moodle Mobile 2 prefixes:

* Core styles should be prefixed with mm-. For example, .mm-split-pane-menu.
* Components styles should be prefixed with mm-componentname-. For example, .mm-login-myclass.
* Addons styles should be prefixed with mma-addonname-. For example, .mma-grades-table.

=== Cordova ===
We use Cordova to access the mobile device APIs. We try to use only core Cordova plugins but sometimes that’s impossible.
If we have to use additional plugins (like Webintents, local notifications, custom URL schemes) we use only plugins well-maintained, generally those listed here: http://plugins.telerik.com/

For integrating Cordova plugins we use ngCordova; ngCordova is a collection of AngularJS extensions on top of the Cordova API that make it easy to build, test, and deploy Cordova mobile apps with AngularJS. The main feature of ngCordova is that instead callbacks it uses promises, so it integrate very well with AngularJS.

=== Testing ===
Tests are written using Jasmine and run using Karma.
Karma is a JavaScript command line tool that can be used to spawn a web server which loads your application's source code and executes your tests.

Jasmine is a behavior-driven development framework for testing JavaScript code. It does not depend on any other JavaScript frameworks. It does not require a DOM. And it has a clean, obvious syntax so that you can easily write tests.

=== Addons ===

The app comes with a predefined set of addons: messages, course contents, notifications, etc. All these addons are inside the www/addons folder. The structure of the files inside an addon is explained in the section App structure and naming conventions.

An addon can be shown in several places. The app has one delegate per each place an addon can be shown, so each addon can register itself to any set of delegates.

The delegates to display data in certain places are:

* $mmSideMenuDelegate: The addons registered in here will be shown in the app’s side menu.
* $mmCoursesDelegate: The addons registered in here will be shown under each course in the course list.
* $mmCourseDelegate: The addons registered in here need to define which module they handle (forum, assign, book, ...). When a user opens a certain module, the addon registered for that module type will be used. There can only be one addon per module type.
* $mmUserDelegate: The addons registered in here will be shown in the user profile page.
* $mmSettingsDelegate: The addons registered in here will be shown in App Settings.
* $mmPluginFileDelegate: The addons registered in here will be able to replace plugin file urls to remove revision number and improve performance when downloading them.

Delegates related to Moodle subsystems or subplugins that in the app will be implemented as subaddons:

* $mmaModQuizAccessRulesDelegate: You can use this service to register your own access rules handlers to be used in a quiz. Addons should be placed in www/addons/mod_quiz/accessrules/
* $mmQuestionBehaviourDelegateProvider: You can use this provider to register your own question behaviour handlers to be used in a quiz or other places. Addons should be placed in www/addons/qbehaviour/
* $mmQuestionDelegateProvider: You can use this provider to register your own question handlers to be used in a quiz or other places. Addons should be placed in www/addons/qtype/
* $mmaModAssignFeedbackDelegate: You can use this provider to register your assign feedback plugins to be used in an assignment. Addons should be placed in www/addons/mod/assign/feedback
* $mmaModAssignSubmissionDelegate: You can use this provider to register your assign submission plugins to be used in an assignment. Addons should be placed in www/addons/mod/assign/submission
* $mmUserProfileFieldsDelegate: You can use this provider to register your user profile fields to be used in user profile. Addons should be placed in www/addons/userprofilefield
* $mmaMessageOutputDelegate: You can use this service to register message output processors to be used in places like notification preferences. Addons should be placed in www/addons/messageoutput/

Finally, the app has some other delegates you can use:

* $mmInitDelegate: You can register processes to be executed while the app is being initialized. It cannot be used from remote addons since they're executed after the init process has ended.
* $mmContentLinksDelegate: The addons registered in here will receive content URLs (from notifications or links clicked) and they need to define which actions can be done for that URL. In the case of links clicked, the first action returned will be automatically triggered. You can use this delegate to intercept clicks on certain URLs and make them redirect to your addon.
* $mmPushNotificationsDelegate: You can use this service to be notified when a push notification is clicked.
* $mmCoursePrefetchDelegate: You should use this provider if your module addon should be downloadable.
* $mmFileUploaderDelegate: You can use this provider to add new ways to upload a file.
* $mmCronDelegate: You can use this service to register tasks that should be executed periodically.
* $mmURLDelegate: You can use this service to be notified when the app is launched using the Custom URL Scheme cordova plugin.

=== Log ===

We use angular’s $log service to log app messages.

A decorator has been applied to $log to add the current date and time and the component to the $log service. If the following instruction is used:

$log.debug(“My message”)

A message like the following is written in the log:

4/27/2015, 11:31:33 AM : My message

To add the component to the message, the following must be done before using $log:

$log = $log.getInstance(“Component”)

From now on the $log messages will have the component, so using the previous $log.debug instruction would print the following now:

4/27/2015, 11:31:33 AM Component: My message

Log can be enabled and disabled. The default value for this is defined in the constant mmCoreDebugDefault.

The log can be enabled/disabled in the app no matter the value of mmCoreDebugDefault. To do so, the following instruction needs to be used:

$mmLog.enabled(true/false)
That change is permanent, so if the app is closed it’s going to remember if the log was enabled or disabled.

There are 5 levels of messages:

* debug: To write messages for debug purposes. It’s the most used in the app.
* error: To log error messages.
* warn: To log warnings (for example, it is used to warn that the Moodle version should be updated).
* log: To log a generic message. Not used.
* info: To write an info message.

=== Events ===

MoodleMobile has a $mmEvents service that allows sending and listening to events in the app. There are two type of events:

* Unique: Thrown only once in the app's lifetime. If a listener is set after the event has been thrown, its callback is going to be called immediately.
* Regular: Can be thrown several times in the app's lifetime. Listeners callbacks will only be called when the event is triggered.

These are the several regular events defined in the app:

* mmCoreEventSessionExpired: Thrown when the user token expires. Param: a string with the site id that expired.
* mmCoreEventLogin: Thrown when the user logins in the app. It is also thrown when the app is started and the user session is restored.
* mmCoreEventLogout: Thrown when the user logouts (go to sites screen).
* mmCoreEventLanguageChanged: Thrown when the language is changed.
* mmCoreEventSiteAdded: Thrown when a new site is added.
* mmCoreEventSiteUpdated: Thrown when a site's data is updated. Params: a string with the site id that was updated.
* mmCoreEventSiteDeleted: Thrown when a site is deleted. Params: site deleted.
* mmCoreEventQueueEmpty: Thrown when the filepool queue is empty.
* Filepool file: Thrown when a filepool file is downloaded or its download fails. The event name is unique for each file. Params: an object with ''success'' property indicating if the download was a success or not.
* mmCoreEventCompletionModuleViewed: Thrown when a module with completion enabled is viewed. Params: courseid.
* mmCoreEventKeyboardShow: Thrown when the keyboard is shown. Params: same as 'native.keyboardshow' event from [https://github.com/driftyco/ionic-plugin-keyboard ionic-plugin-keyboard].
* mmCoreEventKeyboardHide: Thrown when the keyboard is hidden. Params: same as 'native.keyboardhide' event from [https://github.com/driftyco/ionic-plugin-keyboard ionic-plugin-keyboard].
* mmCoreEventUserDeleted: Thrown when we detect that a user has been deleted. Params: an object with siteid and the params sent to the WS call that returned the deleted user error.
* mmCoursesEventMyCoursesUpdated: Thrown when the my courses list should be updated. Params: site id.
* mmaModForumNewDiscussionEvent: Thrown when a discussion is created in the app. Params: forum id, new discussion id and forum cmid.
* mmCoreEventPackageStatusChanged: Thrown when the status of a package changes (e.g. a module). Params: siteid, component, componentId and new status.
* mmCoreEventSectionStatusChanged: Thrown when the status of a course section changes. Params: siteid and sectionid.

=== Core directives ===

MoodleMobile has a set of core directives that can be used by any addon or component. These are some of them.

==== mmAutoFocus ====

Sometimes it's useful to autofocus some input element when a view is loaded, showing the device's keyboard. You just have to add a '''mm-auto-focus''' attribute to your input element and this directive will handle it.

==== mmBrowser ====

Links that are not part of the app (e.g. not buttons) should be opened in a separate browser or app, depending on the platform they are being opened with. A directive was created to make this easy:

'''mm-browser'''

This will catch a click on the link and open it as it should, whether it opens a file, a URL, etc…

Please note that the directive mm-format-text automatically applies mm-browser to all the links found.

Since Moodle Mobile 2.9 the directive mmBrowser uses $mmContentLinksDelegate to detect if the URL belongs to any addon.

==== mmCompletion ====

This directive is meant for activity completion but it can probably be adapted to other uses.

It will display a checkbox showing the current status of the activity. It allows to manually change the status by clicking on it if the activity is configured to do so.

==== mmExternalContent ====

External content is anything that is not locally accessible by the app. If some content has to be made available offline, or saved locally for performance reason, you should be using $mmFilepool. This factory allows you to download files locally, add them to a queue to be downloaded asynchronously, invalidate the local copy, etc…

You can also use the directive mm-external-content which will automatically do the job of adding the files to the queue if they are not find locally.

Please note that at the moment it was decided that mm-external-content would ony work for content that is coming directly from Moodle (pluginfile.php), though it is possible for a developer to be using $mmFilepool with any kind of URLs.

==== mmFile ====

There are several places throughout the app where the user can see a list of files that can be opened or prefetched. This is what this directive is for.

It requires the name and URL of the file, and it will display a list item with the file's name and icon, along with a button to prefetch or refresh the file. This row can be clicked to open the file.

Please notice that these files won't be downloaded unless the user opens or prefetches them.

==== mmFormatText ====

Some of the texts returned by Moodle need to be treated before being rendered since they can include filters, URLs, HTML, etc. You should apply this directive to any text liable to have these.

You just have to wrap the text to format with this directive, something like this:

<nowiki><mm-format-text>{{ content }}</mm-format-text></nowiki>

mmFormatText accepts several parameters to define its behaviour. These are the most important:

* watch: Set it to true if the variable's value could change after the view is rendered. If you set it to false or you don't set it and the variable's value change then the changes won't be reflected in the view.
* after-render: Function to be called when the contents are rendered.
* clean: True if all HTML tags should be removed.
* singleline: True if new lines should be removed (all the text in a single line). Only valid if clean=true.
* shorten: To shorten the text. If a number is supplied then it will shorten the text to that number of characters. If a percentage is supplied then the number of characters to short will be the percentage of element's width. E.g. 50% of an element with 1000px width = 500 characters. Default value is 30%.
* expand-on-click: True if content should be expanded on click (undo shorten). Only valid if shorten=true.
* fullview-on-click: True if full content should be opened in a new view on click. Only valid if shorten=true.

==== mmIframe ====

Iframes can be annoying in Mobile, especially in iOS. This directive is meant to make your life easier when dealing with them.

The non-relative links inside the iframe will be opened using an external browser. Relative links will be opened inside the iframe.

Please notice that all popups opened by the iframe will be blocked since MoodleMobile doesn't support popups.

==== mmImageViewer ====

It's usual to shrink some images in Mobile to make them fit the device's width and height. With this directive you can use an icon or link to see a certain image at full size with scrolling.

Please notice that mmFormatText automatically resizes images to fit the device screen and adds this directive to a magnifying glass icon.

==== mmLoading ====

In most cases the data to show in a view is retrieved from a Moodle site. These operations can take some time, so you should show a loading to show the user that the app is doing something.

This directive will replace your content with a loading spinner until your data is ready. You just need to wrap your HTML code inside this directive:

<nowiki><mm-loading hide-until="eventLoaded"> <ul class="list"> ... </ul> </mm-loading></nowiki>

You need to use the ''hide-until'' attribute to tell the directive when is your data ready. In the example above, when the scope's eventLoaded variable is set to true then the spinner will disappear and the content will be shown.

You can configure the message to show while the spinner is shown (by default, "Loading") and also the spinner's padding top.

==== mmNavigationBar ====

This directive shows a navigation bar with 3 possible buttons: an arrow right, an arrow left and a "info" button.

You can see it in action in IMSCP and SCORM modules.

==== mmNoInputValidation ====

Sometimes we might want to disable automatic validation on some input fields (like URLs). This directive allows us to do so.

==== mmSplitView and mmSplitViewLink ====

It's usual in Mobile apps that in a tablet device you can see 2 views at once in two different panes, while in a smartphone you need to navigate through them 1 by 1. The split view directive allows us to achieve this.

The split view has two panes: the left one (parent or menu) and the right one (child). In tablet the user will be able to see both panels at the same time, but in a smartphone they will be seen as two different views, one at once. Each pane will have its own state, view and controller.

You should place the mm-split-view directive in the template of the '''left''' pane's state. You need to wrap all the HTML that should be in the left pane inside this directive:

<nowiki><mm-split-view component="mmaModForumDiscussionsList">

</mm-split-view></nowiki>

It's important to supply a unique component to the directive to prevent collisions with other split views.

To change the right pane contents, the mmSplitViewLink directive is needed. If you want that the right pane contents change when the user clicks on some links in the left pane, then these links need to have the mm-split-view-link attribute with the state to load. Example:

<nowiki><mm-split-view component="mmaModForumDiscussionsList">
<a mm-split-view-link="site.mod_forum-discussion({cid: courseid, discussionid: discussion.discussion})"></a>
</mm-split-view></nowiki>

In the example above, when the link is clicked the state 'site.mod_forum-discussion' will be loaded in the right pane.

The mmSplitView directive will try to load the first mmSplitViewLink when the view is loaded. You can change the link to load and when it should be loaded by using the attributes "load" and "loadWhen". If you don't have access to the directive's scope but you still want to configure it then you can use the mmCoreSplitViewLoad event. When the directive receives this event it will try to immediately load the link supplied (if no link is supplied then it will load the first link found). Example to load the second link:

<nowiki>$rootScope.$broadcast(mmCoreSplitViewLoad, {load: 2});</nowiki>

'''Important considerations:'''

* The directive mm-split-view-link needs to be placed inside a mm-split-view, otherwise it won't work. Both directives need to be in the left pane template, placing any of them in the right pane template can cause errors and unexpected behaviour.
* Due to a limitation in Angular ui-router, the left pane state and the right pane state should NOT have parameters with the same name but different value, it can cause unexpected behaviors. Example: if the left pane loads a state with param 'courseid', then all the states that can be loaded in the right pane should avoid having a parameter named 'courseid'. The right pane state can have a 'courseid' param only if it will always have the same value than in left pane state. This is due to state hierarchy in ui-router.

=== URL scheme API ===

The Moodle Mobile app can be opened using links via the app's custom URL scheme:

Links are of the form <syntaxhighlight lang="php">moodlemobile://link=https://yourmoodlesite.org/mod/...</syntaxhighlight>

For example, the link <syntaxhighlight lang="php">moodlemobile://link=https://mysite.es/mod/choice/view.php?id=8</syntaxhighlight> will open the mobile app and display a choice activity.

You can specify an user (if you can guess the current user username) <syntaxhighlight lang="php">moodlemobile://link=jsmith@https://mysite.es/mod/choice/view.php?id=8</syntaxhighlight>

If the user has the mobile app installed in his device and he is logged in the site or he added the site, the app will display the resource required. If the site wasn't added, the app will require the user credentials for that site.

== Development ==

See [[Moodle Mobile Plugins Development]].

Source code:

* https://github.com/moodlehq/moodlemobile2

== Creating your custom app ==

See [[Moodle Mobile Customization]].

== See also ==

* [[Moodle Mobile Customization]]
* [[Moodle Mobile Plugins Development]]

Moodle Mobile 1 Developing a plugin tutorial

2022-04-29T07:08:55Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 1}}
== Introduction ==
This tutorial describes all the steps needed for developing a plugin for the MoodleMobile app.

In this tutorial we make the following assumptions:
* You have a medium/good skills/understand of Javascript, PHP and Moodle architecture
* You know what a Web Service is and how it works in Moodle
* The plugin you are going to develop requires a Web Service in your Moodle installation to work
'''Notice that neither the moodle plugin code and the moodle mobile plugin code are suitable for production environments'''

There is a second part of this tutorial where we extend the current WebServices and create a new "forums" plugin, see [[Moodle Mobile Developing a plugin tutorial part 2]]
== Plugin spec ==
We want to develop a "grades" plugin that will display the current user grades for all the gradable activities in a course the user is enroll in.

A screenshot of the desired result:

[[File:MoodleMobileTutorial01.png]]

As you can see there is a new menu called "Grades" that displays a page in the middle panel showing all the course activities. When we click in an activity, the right panel shows the grade / maximum grade for the current user.

In order to achieve this we will have to develop:
* A plugin for Moodle containing a new Web Service that returns grades and..
* A MoodleMobile plugin
== Steps ==
=== Set up your development environment ===
Clone or fork the official git repository [https://github.com/moodlehq/moodlemobile] in a local directory.

Set up your development browser, see [[Moodle_Mobile]], I mainly use the Google Chrome browser.
=== Set up your Moodle installation ===
Enable debugging, disable caches, etc... the typical settings for developing.

Enable the Web Services and also the protocols you are going to use for testing and developing (REST is mandatory). See [[Web Services]] documentation.

Enable the Mobile Service

Enable the moodle/webservice:createtoken capability for the Authenticated User Role at System Context
=== Develop the Moodle local/mod/block/... plugin ===
You can find the full source code here:
https://github.com/cvaconsulting/moodle-local_custommm

In this case we've developed a local plugin that contains a Web Service that returns grades as described here: https://tracker.moodle.org/browse/MDL-30085

Notice that my version has some differences with the previous mentioned one. I have fixed some small bugs and changed some parameters.
=== Test your Web Services using a demo client ===
Before continuing you must test that your Web Service works, the local plugin contains a demo REST client, see:

https://github.com/cvaconsulting/moodle-local_custommm/blob/master/client/client.php
=== Create your custom Service ===
A service is a set of functions for an specific purpose. Since Moodle 2.1 there is a pre-built service that contains all the functions needed for the official mobile app.

This service cannot be edited for adding new functions so we don't have a simple way for make available our new Web Service function to the mobile app.

The only way for fix this is creating a new Service in Moodle, and configuring our app for pointing to this new service.

There are two ways of creating a Service in Moodle:
* Using a db/services.php in your plugin as mentioned here: [[External services description]]

* Creating the service in your Moodle installation using the forms in Admin > Plugins > Web Services > External Services
In this case we've created the service using the Moodle forms because it gives more flexibility in some aspects, there is a big impediment, due to https://tracker.moodle.org/browse/MDL-29807 in order to add a shortname for the new Service, we have to edit manually the Moodle database for adding the shortname in the dbprefix_external_services table

[[File:MoodleMobileTutorial02.png]]

When creating, the flats "Can download files" and "Enabled" must be checked.
=== Set up your MoodleMobile client ===
The most important change you have to do is edit the config.json file and change the wsservice parameter in order to point to the shortname of the Service you created before.

You have to add also the name of the plugin you are developing at the final of the plugins parameter:

"plugins" : ["notifications", "upload", "contents", "participants", "addcontact", "addnote", "sendmessage", "grades"],

Notice that, for avoid errors, this last change should be done once the file plugins/grades/main.js file exists
=== Develop the MoodleMobile plugin ===
The full source code can be found here:

https://github.com/cvaconsulting/moodlemobile-grades

https://github.com/cvaconsulting/moodlemobile-grades/blob/master/lang/en.json - Contains the language strings, the string "pluginPLUGINname" is mandatory

https://github.com/cvaconsulting/moodlemobile-grades/blob/master/icon.png - The plugin icon

https://github.com/cvaconsulting/moodlemobile-grades/blob/master/activities.html - The template for the activities list (center panel)

https://github.com/cvaconsulting/moodlemobile-grades/blob/master/activitygrade.html - The template for showing the grade for an activity (right panel)

https://github.com/cvaconsulting/moodlemobile-grades/blob/master/main.js - The plugin's main code

Bellow, I summarize the most important parts of the code (always parts of the main.js file):
<syntaxhighlight lang="javascript">

var templates = [
"root/externallib/text!root/plugins/grades/activities.html",
"root/externallib/text!root/plugins/grades/activitygrade.html",
"root/externallib/text!root/plugins/grades/lang/en.json"
];

define(templates,function (activities, activityGrade, langStrings) {
var plugin = {
settings: {
name: "grades",
type: "course",
menuURL: "#course/grades/",
lang: {
component: "local_custommm",
strings: langStrings
}
},

</syntaxhighlight>
Notice that we required three files, the two templates (.html) and the .json file that contains the lang strings.

In the plugin.settings structure, we define the lant attribute that contains two very important attributes:
* Component: It must refer to the Moodle component linked to this plugin
* strings: The lang strings in .json format (plain text). As you can see, with this line we are populating the plugin.settings.lang.strings var withe the contents of the lang/en.json files
<syntaxhighlight lang="javascript">

viewActivities: function(courseId) {

MM.panels.showLoading('center');

if (MM.deviceType == "tablet") {
MM.panels.html('right', '');
}

var data = {
"options[0][name]" : "",
"options[0][value]" : ""
};
data.courseid = courseId;

MM.moodleWSCall('core_course_get_contents', data, function(contents) {
var course = MM.db.get("courses", MM.config.current_site.id + "-" + courseId);

var tpl = {
sections: contents,
course: course.toJSON() // Convert a model to a plain javascript object.
}
var html = MM.tpl.render(MM.plugins.grades.templates.activities.html, tpl);
MM.panels.show("center", html);
});
},

</syntaxhighlight>
The viewActivities is the function that displays in the center panel the list of activities inside a course, as you can see the code is pretty simple.
* We call to the core_course_get_contents Web Service that returns all the activities and resources inside a course
* We render the template that will iterate over the sections and activities displaying the links to specifics activities
<syntaxhighlight lang="javascript">
viewActivityGrade: function(activityName, courseId, modName, cmId) {

if (MM.deviceType == "tablet") {
MM.panels.showLoading('right');
}

var data = {
"grades[courseid]" : courseId,
"grades[component]" : "mod_" + modName,
"grades[cmid]" : cmId,
"grades[userids][0]" : MM.config.current_site.userid
};

MM.moodleWSCall('local_custommm_get_grades', data, function(contents) {
var course = MM.db.get("courses", MM.config.current_site.id + "-" + courseId);

var grade= MM.lang.s("nogrades", "grades");

if(contents.items[0]) {
grade = contents.items[0]["grades"][0]["str_long_grade"];
}

var tpl = {
activityName: activityName,
sections: contents,
finalGrade: grade,
course: course.toJSON(), // Convert a model to a plain javascript object.
items: contents
}
var html = MM.tpl.render(MM.plugins.grades.templates.activityGrade.html, tpl);
MM.panels.show("right", html);
if (MM.deviceType == "tablet" && contents.length > 0) {
// First section.
MM.plugins.contents.viewCourseContentsSection(courseId, 0);
}
});
},
</syntaxhighlight>
This function gets and displays the grade for the selected activity in the centered panel.

We just call to the Web Service we developed and parse the result, if nothing is returned we display a generic message indicating that there is no grades information for the activity.
If a grades full structure is returned, we return the first grade for the first grade items (as Moodle usually does) that corresponds to the user grade for the activity

Notice that:
* Some activities, like workshop, returns two different grades items (teacher and peer grades). The example doesn't implement any logic for this case.
* Some activities may return outcomes. The example doesn't implement any logic for this case.
* The rest grade information (grade min, grade max, feedback) is also covered by this example.
=== Deliver your plugin ===
Android: Package your plugin using ''PhoneGap build''

iOs: Further instructions soon
== See also ==
[[Moodle Mobile Developing a plugin tutorial part 2]]

Moodle Mobile 1

2022-04-29T07:06:02Z

Pferre22:

{{Template:WillNotMigrate}}
<p class="note">For user documentation see '''[[:en:Moodle Mobile|Moodle Mobile]]'''.</p>
{{Moodle Mobile 1}}

IMPORTANT: This documentation is for the former official version of the Moodle Mobile application (not maintained anymore and not available in the stores), documentation for the new version is available in [[Moodle Mobile]]

== General Overview ==

MM (Moodle Mobile) is the official mobile app for Moodle. MM is an HTML5 app that uses common web technologies.

Basically, is a Web Services client that uses REST as protocol to obtain and send information to your Moodle installation/s.

The layout is created using HTML5 and CSS3, interaction with the phone and packaging is done using Phonegap.

For calling the Web Services, manipulating the DOM and interacting with Phonegap, we use jQuery as our Javascript framework.

This app is a replacement of the old [[Mobile app]], see the discussion [https://moodle.org/mod/forum/discuss.php?d=206736 Change in our Moodle mobile app strategy] for details.

== Features ==

The features are going to be the same that the old [[Mobile app]] plus:

* PUSH Notifications (only iOs in first version)
* Mobile and tablet version (Responsive design)
* Support for contrib plugins
* Support for external settings: Extra CSS
* New development and debugging features

Features for future versions:

* Calendar sync
* Offline browsing and posting in forums
* Offline grading

== Requirements ==

* Moodle 2.4

Future versions will require the last minor versions if Web Services are not backported.

== Technologies used ==

* HTML5 http://www.w3.org/TR/2011/WD-html5-20110525/

* CSS3 http://www.w3.org/Style/CSS/

* Media queries for screen width and height http://www.w3.org/TR/css3-mediaqueries/

* Phonegap http://wiki.phonegap.com/w/page/16494772/FrontPage

* jQuery http://jquery.com/

* jQuery UI http://jqueryui.com/

* jQuery touchSwipe http://labs.skinkers.com/touchSwipe/

* matchMedia https://github.com/paulirish/matchMedia.js/

* Backbone and Underscore http://backbonejs.org/

* RequireJS requirejs.org

* jsdoc http://code.google.com/p/jsdoc-toolkit/

* Google Javascript Style Guide http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml

* Google Closure Lint http://code.google.com/p/closure-linter/

=== Phonegap ===

MM uses Phonegap for using Moodle hardware/software features like Camera, Audio/video recorder, access to the file system, etc.
Phonegap is loaded in the index page of the app (jQuery, the main lib of the app are also loaded in the index page).

=== jQuery ===

For DOM manipulation and some helper functions, is a requirement of others libraries listed below.

=== jQuery UI ===

Dialogs and also for enhancing forms elements (buttons, checkboxes, etc...)

=== jQuery touchSwipe ===

For detecting mouse gestures

=== matchMedia ===

Javascript detection of media queries

=== Backbone and Underscore ===

For storage (Models and Collections), Underscore templates, and URL Routing

=== RequireJS ===

For handling modules dependencies and loading plugins

== Structure of the app (only main directories) ==

css/ - App main layout and styles
img/ - App images
lang/ - Default lang
lib/ - Main libraries
plugins/ - Plugins
test/ - Test data when developing in Test mode
config.json - Main app configuration file (presets)
index.html - Index page of the app

== Getting and sending information to Moodle ==

MM uses standard Moodle Web Services for getting and sending information to Moodle.
AJAX (jQuery) and REST + JSON are the technologies used.

Notice that mobile HTML5 apps doesn’t have cross domain restrictions so you can make AJAX calls to any domain.

== External settings ==

In your Moodle installation you can specify an extra CSS file for customizing the app remotely.

This CSS is downloaded and stored in the device database for further use.

== Storage ==

We use HTML5 localStorage that is cross browser implemented and there are libraries that can work of top of it.

We use Backbone Models and Collections as a wrapper for localStorage.

Note that localStorage has some limitations like a 5MB max size in some devices and also is considers "Temporal data" for some devices like the new iPhones.

== Internationalization ==

The app includes a language file in JSON (English as the default language).

Other language packs are available, full list here:

https://github.com/moodlehq/moodlemobile/tree/master/lang

For translating the app to your language, you can use the [http://lang.moodle.org AMOS tool] Translations from this tool are periodically synchronized with new versions in the app

== Plugins ==

=== Overview ===

Plugins allow developers to extend the app functionalities.
A plugin it’s a subdirectory that implements a set of required functionalities.

=== Types of plugins ===

* General: Interactions over the global app, such as the Notifications, Upload, Help and Web
* Course: Interactions over a course, such as course contents or participants
* User: Interactions over an user, such as send a message, add as a contact, write a private note
* Settings: Additional settings for the app

=== Development ===

See [[Moodle Mobile Plugins Development]].

There are a couple of tutorials with two sample plugins (grades and forums plugins)

See [[Moodle Mobile Developing a plugin tutorial]] and [[Moodle Mobile Developing a plugin tutorial part 2]]

Source code:

* https://github.com/moodlehq/moodlemobile

== Creating your custom app ==

See [[Moodle Mobile Customization]].

== Limitations and disadvantages of HTML5 apps ==

* Less speed and smoothness

* Limited to the Mobile functionalities provided from Phonegap

== FAQ ==

=== Is the app a replacement of the MyMobile theme? ===
No, see http://moodle.org/mod/forum/discuss.php?d=206736#p901751

=== What is the difference between a native app and a Mobile specific theme or responsive theme? ===

See http://moodle.org/mod/forum/discuss.php?d=206736#p901475

Also http://moodle.org/mod/forum/discuss.php?d=206736#p901751

== See also ==

* [[Moodle Mobile Customization]]
* [[Moodle Mobile Plugins Development]]
* [[Moodle Mobile Building the app for Android]]
* [[Moodle Mobile Building the app for iOS]]
* [http://es.slideshare.net/juanleyva/creating-a-custom-moodle-mobile-app-moodle-moot-spain-2014 Creating a custom Moodle Mobile app - MoodleMoot Spain 2014]

[[es:Moodle Mobile]]

Moodle Mobile 1 Customization

2022-04-29T07:05:56Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle Mobile 1}}
== Overview ==
In this document are described the general steps for building your custom Mobile app.

You can find a step by step guide of how to create a custom version of the app here: http://es.slideshare.net/juanleyva/creating-a-custom-moodle-mobile-app-moodle-moot-spain-2014
== Creating your custom application ==
Remember that if you only want to change the global styles of the app, you can use an extra CSS file in your Moodle installation without needing to recompile the app.
=== Basic custom settings ===
In your Moodle installation you can specify a extra CSS file in the Mobile settings section

You can edit the config.json file for:
- Adding a default language
- Add some presets in the login screen (url and username) pointing to your installation
=== Development environment ===
See [[#Testing_and_developing]]

It is recommended that you have a local web server (app and moodle installation under localhost or the same local domain).

You will need:
* A Moodle installation with Web Services (REST) enabled - see [[Web services]] documentation
:* Administration -> Plugins -> Web Services -> External Services -> Enable mobile web service

:* Administration -> Plugins -> Web Services -> Protocols -> Enable REST

:* Administration -> Users -> Permission -> Define roles -> Edit the Authenticated user role -> Allow webservice/rest:use
* A local copy of the Mobile HTML5 App with the Debugging options Enabled (https://github.com/moodlehq/moodlemobile)
=== Web Services Development ===
In most cases your plugin/s will need Web Services to get data from your Moodle installation. It is recommended that you first develop the Web Services that you will need (see [[Web Services]]).
* Create a local plugin in Moodle for adding the extra Web Services you need and also your plugin's lang files (Local WS plugin template: https://moodle.org/plugins/view.php?plugin=local_wstemplate)

* Create a new External Service in your Moodle installation, adding a services.php file in your new local plugin or creating manually the service in your Moodle installation.(Plugins -> Web Services) See [[External services description]] for more info. Remember the key name of the service, because you will need it later.
=== Moodle Mobile Plugin Development ===
See [[Moodle Mobile 1 Plugins Development]] and [[Moodle Mobile 1 Developing a plugin tutorial]]

For developing the plugin you need:
* Edit the /config.json file to:
:* Add the extra plugins you implement
:* Indicate the WS service name you are going to use in your Moodle installation (Remember, that you need to create a WS Service indicating the functions available for your custom app)
:* Add your custom default lang file (es, ca, fr ...) (the language file must exists in the app's lang/ folder)
:* Change the app login form presets
* Add your own css files, custom images, etc..
=== Building ===
There are three options for building the app, aka compile it to different devices:

'''Phonegap Build'''

''Phonegap Build'' is an online service that let you to build the app automatically for different platforms. The main advantage is that simplify a lot the process of building.

You just put your customizations in a github account and Phonegaps automatically build the app for different platforms pulling your github code.

Notice that the free version is for open repositories, but you can use the non-free version for private repositories.

'''Phonegap CLI'''

You can build also using the Phonegap CLI interface, it requires to install the different Platform SDK / tools but the build process is simpler.

Once installed the environment, you need to deploy in your project/www folder the app code

'''Platform SDK'''

See [[Moodle Mobile Building the app for Android]] or [[Moodle Mobile Building the app for iOS]] (These articles may be obsolete)

'''Automatic build system'''

See [[Moodle Mobile Automatic Building System]] for some instructions for building an automatic building system initially for Android.
== Testing and developing ==
=== Chromium or Google Chrome browser ===
See [[Moodle Mobile development using Chrome or Chromium]]
=== Ripple ===
Requirements: Google Chrome browser + Ripple mobile environment emulator plugin (http://ripple.tinyhippos.com/)

You must run Google Chrome in Unsafe mode adding this param:
--allow-file-access-from-files
IMPORTANT: I strongly recommend you create a new link or application launch called "Google Unsafe" and use it only for testing the app.
"Path to chrome\chrome.exe" --allow-file-access-from-files
Open the index.html file in the Google Chrome unsafe and click on the Ripple icon to activate the emulator.

Once opened in the Ripple settings block, change Cross Domain Proxy to Disabled.

Please note that some functionalities (camera, audio recording, contact) will not work in the emulator.
=== Platform SDK ===
Install the Android or iPhone SDK.
=== Debugging styles or running a remote Console ===
You can use Safari or Google Chrome developer tools for debugging (console) and changing the CSS styles in live:

https://developer.chrome.com/devtools/docs/remote-debugging

http://phonegap-tips.com/articles/debugging-ios-phonegap-apps-with-safaris-web-inspector.html

=== Local web server ===
If you deploy the html files in a server under the same domain that the Moodle you are going to connect to you can test the application without emulator or changing the Security settings of your browser.

In other words

Your Moodle at http://myhost.com/moodle24

Your app at http://myhost.com/moodlemobile/

or

Your Moodle at http://localhost/moodle24

Your app at http://localhost/moodlemobile/

Note that the mobile - related modules will not work.
== See also ==
[http://es.slideshare.net/juanleyva/creating-a-custom-moodle-mobile-app-moodle-moot-spain-2014 Creating a custom Moodle Mobile app - MoodleMoot Spain 2014]

Moodle Desktop release notes

2022-04-29T07:05:05Z

Pferre22:

{{Template:WillNotMigrate}}
<p class="note">Note: [https://moodle.org/mod/forum/discuss.php?d=413350 Moodle Desktop is discontinued] since 1 May 2021.</p>

{| class="wikitable"
|-
! Version name
! Date
! Platforms
! Notes
|-
! Moodle Desktop 3.7.2
| 20 September 2019
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.7.2_release_notes|Moodle Mobile 3.7.2]]
|-
! Moodle Desktop 3.7.1
| -
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| Version skipped due to a security issue detected in Moodle App 3.7.1
|-
! Moodle Desktop 3.7.0
| 12 Julio 2019
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.7.0_release_notes|Moodle Mobile 3.7.0]]
|-
! Moodle Desktop 3.6.1
| 14 May 2019
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.6.1_release_notes|Moodle Mobile 3.6.1]] plus the following desktop-specific improvement:
* It is now possible to enable the "Developer Tools" in the Desktop app using the same key combinations that the Chrome browser: "Control + Shift + I" (in MacOs is Command + Option + I).
|-
! Moodle Desktop 3.6.0
| 3 February 2019
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.6.0_release_notes|Moodle Mobile 3.6.0]]
|-
! Moodle Desktop 3.5.2
| 19 September 2018
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.5.2_release_notes|Moodle Mobile 3.5.2]]
|-
! Moodle Desktop 3.5.1
| 25 July 2018
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.5.1_release_notes|Moodle Mobile 3.5.1]]
|-
! Moodle Desktop 3.5.0
| -
|
-
| Skipped, see Moodle Desktop 3.5.1
|-
! Moodle Desktop 3.4.2
| 20 March 2018
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.4.2_release_notes|Moodle Mobile 3.4.2]]
|-
! Moodle Desktop 3.4.1
| 1 March 2018
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.4.1_release_notes|Moodle Mobile 3.4.1]]
|-
! Moodle Desktop 3.4.0
| 1 December 2017
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.4.0_release_notes|Moodle Mobile 3.4.0]]
|-
! Moodle Desktop 3.3.2
| 29 September 2017
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.3.2_release_notes|Moodle Mobile 3.3.2]] plus:
* New 32 bits version for Linux
|-
! Moodle Desktop 3.3.1
| 8 August 2017
|
* Windows 7, 8 and 10
* macOS
* Linux
| With all the features of [[Moodle_Mobile_3.3.1_release_notes|Moodle Mobile 3.3.1]] plus the following desktop-specific improvements:
* The app keeps the focus when re-opened via the status bar
* Scroll down on pages using a scroll wheel or trackpad gesture is now supported
|-
! Moodle Desktop 3.3.0
| 5 July 2017
| Windows 10
| With all the features of [[Moodle_Mobile_3.3.0_release_notes|Moodle Mobile 3.3.0]]
|}

== See also ==
* [[:en:Moodle Desktop|Moodle Desktop user documentation]]
* [[Moodle Mobile release notes]]

[[Category:Mobile]]

Moodle Desktop

2022-04-29T07:02:40Z

Pferre22:

{{Template:WillNotMigrate}}
{{Moodle App (Ionic 3)}}
<p class="note">Note: [https://moodle.org/mod/forum/discuss.php?d=413350 Moodle Desktop is discontinued] since 1 May 2021.</p>
[http://download.moodle.org/desktop/ Moodle Desktop] is build using the popular framework [http://electron.atom.io/ Electron].

Electron is a very popular cross-platform for building desktop apps with JavaScript, HTML, and CSS.

If you want to build your custom version of Moodle Desktop, please follow the Electron Guides that you will find in https://electron.atom.io/docs/

Please, consider the following:
* For building a Windows version you will need a Windows computer.
* The Mac version will require a Mac computer.
* The Linux version may require a Linux distribution (depending on the selected target).

Note also that if you want to publish your custom versions in the Windows or Apple stores, you will need to sign-up for a developer account (it costs money).

Moodle HQ provides a branding service of Moodle Desktop via the [https://moodle.com/mobileapp/ The Branded Moodle Mobile App]. This service includes publishing in the stores and code signing.

== I'm feeling lucky ==

If you are already familiar with Electron (or simply want to get your feet wet before diving deeper), you can get started easily. But first, you'll have to grab a copy of [https://github.com/moodlehq/moodlemobile2 Moodle Mobile 2] from Github. See our docs [https://docs.moodle.org/dev/Setting_up_your_development_environment_for_Moodle_Mobile_2#Clone_the_app_base_code here] if you need help.

Once you have a copy, you'll see that there is a folder named ''desktop'' located in the root directory.
This is where the Electron configuration file for the desktop app is located (aptly named "electron.js").
When we build our app, the distribution files will also be placed in this folder.
The "electron.js" file defines the configuration for the desktop app with sane defaults.
You can modify it if you want to (you don't really have to though) and use either of these scripts to build the desktop app :

<syntaxhighlight lang="php">npm run desktop.pack</syntaxhighlight> (only generates the package directory without really packaging it. This is useful for testing purposes)
<syntaxhighlight lang="php">npm run desktop.dist</syntaxhighlight> (to package in a distributable format (e.g. dmg, windows installer, deb package))

== Troubleshooting ==

=== Deleting the profile ===

Sometimes the app can get into a bad state and you might want to delete its data. When using the desktop environment, you need to delete the contents of the profile folder.

* On Windows this can sometimes be found at C:\Users\ (your username) \AppData\Roaming\moodlemobile

Just quit the app, delete all the files in this folder, and open it again; you'll start with a fresh app.

Contributing to the Moodle app

2022-04-29T07:00:59Z

Pferre22:

{{Template:WillNotMigrate}}

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

[[Category:Mobile]]

Moodle App 4.0.0 release notes

2022-04-28T13:54:28Z

Pferre22:

[[Moodle App Release Notes|Moodle App release notes]] > {{FULLPAGENAME}}

Release date: 25 April 2022

Please notice this new version will only connect Moodle sites version >= 3.5 and that it won't work if your site is using the deprecated local_mobile (Mobile app additional features) plugin.
==New features and improvements==
* Support Moodle 4.0 LMS new "My courses" page
* User profile repositioned to match LMS
* Design updated to Material design 3 matching overall Moodle style
* Some pages now support swipe (participants, book module, grades, forum discussions,...)
* Resuming a course or a book is now easier
* Course main page additional options menu redesigned
* Navigation between sections and activities improved
* SCORM, H5P automatic full-screen mode
* Thumbnails for videos are automatically generated
* Content and activities pages with fewer distractions for users so they can focus on learning
* General performance improvements
* New notifications page (capturing all the notifications received by the user)
* The enrolment fee plugin is now supported (launched in a browser outside the app to complete the process)
* New 4.0 assignment time-limited submissions supported
* Teachers can now see H5P attempt reports
==Complete list of issues==

=== Bug ===

=== New Feature ===

=== Task ===

=== Improvement ===

=== Sub-task ===
[[Category:Mobile]]
[[Category:Release notes]]

Moodle App 4.0.0 release notes

2022-04-28T13:54:03Z

Pferre22:

[[Moodle App Release Notes|Moodle App release notes]] > {{FULLPAGENAME}}

Release date: 25 April 2022
==New features and improvements==
* Support Moodle 4.0 LMS new "My courses" page
* User profile repositioned to match LMS
* Design updated to Material design 3 matching overall Moodle style
* Some pages now support swipe (participants, book module, grades, forum discussions,...)
* Resuming a course or a book is now easier
* Course main page additional options menu redesigned
* Navigation between sections and activities improved
* SCORM, H5P automatic full-screen mode
* Thumbnails for videos are automatically generated
* Content and activities pages with fewer distractions for users so they can focus on learning
* General performance improvements
* New notifications page (capturing all the notifications received by the user)
* The enrolment fee plugin is now supported (launched in a browser outside the app to complete the process)
* New 4.0 assignment time-limited submissions supported
* Teachers can now see H5P attempt reports
==Complete list of issues==

=== Bug ===

=== New Feature ===

=== Task ===

=== Improvement ===

=== Sub-task ===
[[Category:Mobile]]
[[Category:Release notes]]

Moodle App 4.0.0 release notes

2022-04-28T13:53:27Z

Pferre22: Created page with "Moodle Mobile release notes > {{FULLPAGENAME}} Release date: 25 April 2022 ==New features and improvements== * Support Moodle 4.0 LMS new "My courses" page * User profile..."

[[Moodle Mobile release notes]] > {{FULLPAGENAME}}

Release date: 25 April 2022
==New features and improvements==
* Support Moodle 4.0 LMS new "My courses" page
* User profile repositioned to match LMS
* Design updated to Material design 3 matching overall Moodle style
* Some pages now support swipe (participants, book module, grades, forum discussions,...)
* Resuming a course or a book is now easier
* Course main page additional options menu redesigned
* Navigation between sections and activities improved
* SCORM, H5P automatic full-screen mode
* Thumbnails for videos are automatically generated
* Content and activities pages with fewer distractions for users so they can focus on learning
* General performance improvements
* New notifications page (capturing all the notifications received by the user)
* The enrolment fee plugin is now supported (launched in a browser outside the app to complete the process)
* New 4.0 assignment time-limited submissions supported
* Teachers can now see H5P attempt reports

==Complete list of issues==

=== Bug ===

=== New Feature ===

=== Task ===

=== Improvement ===

=== Sub-task ===

[[Category:Mobile]]
[[Category:Release notes]]

Moodle App Release Notes

2022-04-28T13:51:31Z

Pferre22:

== Moodle App ==
{| class="wikitable"
|-
! Version name
! Date
! Version code
!
|-
!Moodle App 4.0.0
|25 April 2022
|40000
|[[Moodle App 4.0.0 release notes|Release Notes]]
|-
! Moodle App 3.9.5
| 27 August 2021
| 39500
| [[Moodle Mobile 3.9.5 release notes|Release Notes]]
|-
! Moodle App 3.9.4
| 28 December 2020
| 39400
|[[Moodle Mobile 3.9.4 release notes|Release Notes]]
|-
! Moodle App 3.9.3
| 30 November 2020
| 39300
| [[Moodle Mobile 3.9.3 release notes|Release Notes]]
|-
! Moodle App 3.9.2
| 16 July 2020
| 39200
| [[Moodle Mobile 3.9.2 release notes|Release Notes]]
|-
! Moodle App 3.9.1
| 3 July 2020
| 39100
| [[Moodle Mobile 3.9.1 release notes|Release Notes]]
|-
! Moodle App 3.9.0
| 26 June 2020
| 39000
| [[Moodle Mobile 3.9.0 release notes|Release Notes]]
|-
! Moodle App 3.8.2
| 2 April 2020
| 38200
| [[Moodle Mobile 3.8.2 release notes|Release Notes]]
|-
! Moodle App 3.8.1
| 25 March 2020
| 38100
| [[Moodle Mobile 3.8.1 release notes|Release Notes]]
|-
! Moodle App 3.8.0
| 20 December 2019
| 38000
| [[Moodle Mobile 3.8.0 release notes|Release Notes]]
|-
! Moodle App 3.7.2
| 20 September 2019
| 37200
| [[Moodle Mobile 3.7.2 release notes|Release Notes]]
|-
! Moodle App 3.7.1
| 30 August 2019
| 37100
| [[Moodle Mobile 3.7.1 release notes|Release Notes]]
|-
! Moodle App 3.7.0
| 7 June 2019
| 37000
| [[Moodle Mobile 3.7.0 release notes|Release Notes]]
|-
! Moodle App 3.6.1
| 29 March 2019
| 36100
| [[Moodle Mobile 3.6.1 release notes|Release Notes]]
|-
! Moodle App 3.6.0
| 11 January 2019
| 36000
| [[Moodle Mobile 3.6.0 release notes|Release Notes]]
|-
! Moodle App 3.5.2
| 10 September 2018
| 35200
| [[Moodle Mobile 3.5.2 release notes|Release Notes]]
|-
! Moodle App 3.5.1
| 6 July 2018
| 35100
| [[Moodle Mobile 3.5.1 release notes|Release Notes]]
|-
! Moodle App 3.5.0
| 25 June 2018
| 35000
| [[Moodle Mobile 3.5.0 release notes|Release Notes]]
|}
== Moodle Mobile ==
Versions with support or 3.0 and previous versions, based on Ionic 1.
{| class="wikitable"
|-
! Version name
! Date
! Version code
!
|-
! Moodle Mobile 3.4.2
| 19 March 2018
| 20230
| [[Moodle Mobile 3.4.2 release notes|Release Notes]]
|-
! Moodle Mobile 3.4.1
| 28 February 2018
| 20220
| [[Moodle Mobile 3.4.1 release notes|Release Notes]]
|-
! Moodle Mobile 3.4.0
| 30 November 2017
| 20210
| [[Moodle Mobile 3.4.0 release notes|Release Notes]]
|-
! Moodle Mobile 3.3.2
| 29 September 2017
| 20200
| [[Moodle Mobile 3.3.2 release notes|Release Notes]]
|-
! Moodle Mobile 3.3.1
| 28 July 2017
| 20190
| [[Moodle Mobile 3.3.1 release notes|Release Notes]]
|-
! Moodle Mobile 3.3.0
| 26 May 2017
| 20180
| [[Moodle Mobile 3.3.0 release notes|Release Notes]]
|-
! Moodle Mobile 3.2.1
| 28 February 2017
| 20170
| [[Moodle Mobile 3.2.1 release notes|Release Notes]]
|-
! Moodle Mobile 3.2.0
| 12 December 2016
| 20160
| [[Moodle Mobile 3.2.0 release notes|Release Notes]]
|-
! Moodle Mobile 3.1.3
| 19 October 2016
| 20150
| [[Moodle Mobile 3.1.3 release notes|Release Notes]]
|-
! Moodle Mobile 3.1.2
| 27 July 2016
| 2014
| [[Moodle Mobile 3.1.2 release notes|Release Notes]]
|-
! Moodle Mobile 3.1.1
| 14 June 2016
| 2013
| [[Moodle Mobile 3.1.1 release notes|Release Notes]]
|-
! Moodle Mobile 3.1.0
| 23 May 2016
| 2012
| [[Moodle Mobile 3.1.0 release notes|Release Notes]]
|-
! Moodle Mobile 3.0.0
| 15 April 2016
| 2011
| [[Moodle Mobile 3.0.0 release notes|Release Notes]]
|-
! Moodle Mobile 2.9
| 29 February 2016
| 2010
| [[Moodle Mobile 2.9 release notes|Release Notes]]
|-
! Moodle Mobile 2.8
| 22 January 2016
| 2009
| [[Moodle Mobile 2.8 release notes|Release Notes]]
|-
! Moodle Mobile 2.7
| 29 December 2015
| 2008
| [[Moodle Mobile 2.7 release notes|Release Notes]]
|-
! Moodle Mobile 2.6
| 27 November 2015
| 2007
| [[Moodle Mobile 2.6 release notes|Release Notes]]
|-
! Moodle Mobile 2.5
| 6 November 2015
| 2006
| [[Moodle Mobile 2.5 release notes|Release Notes]]
|-
! Moodle Mobile 2.4
| 21 October 2015
| 2005
| [[Moodle Mobile 2.4 release notes|Release Notes]]
|-
! Moodle Mobile 2.3
| 8 October 2015
| 2004
| [[Moodle Mobile 2.3 release notes|Release Notes]]
|-
! Moodle Mobile 2.2
| 10 September 2015
| 2003
| [[Moodle Mobile 2.2 release notes|Release Notes]]
|-
! Moodle Mobile 2.1
| 28 August 2015
| 2002
| [[Moodle Mobile 2.1 release notes|Release Notes]]
|-
! Moodle Mobile 2.0
| 31 July 2015
| 2000
| [[Moodle Mobile 2.0 release notes|Release Notes]]
|}
== Moodle Mobile 1 ==
See [[Moodle Mobile 1 release notes]]
== See also ==
* [[Moodle Desktop release notes]]
* [[Moodle Mobile Roadmap]]
[[Category: Mobile]]
[[Category:Release notes]]

Contributing to the Moodle app

2022-04-26T15:23:25Z

Pferre22:

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

[[Category:Mobile]]

Moodle Desktop release notes

2022-04-25T11:02:23Z

Pferre22:

<p class="note">Note: [https://moodle.org/mod/forum/discuss.php?d=413350 Moodle Desktop is discontinued] since 1 May 2021.</p>

{| class="wikitable"
|-
! Version name
! Date
! Platforms
! Notes
|-
! Moodle Desktop 3.7.2
| 20 September 2019
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.7.2_release_notes|Moodle Mobile 3.7.2]]
|-
! Moodle Desktop 3.7.1
| -
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| Version skipped due to a security issue detected in Moodle App 3.7.1
|-
! Moodle Desktop 3.7.0
| 12 Julio 2019
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.7.0_release_notes|Moodle Mobile 3.7.0]]
|-
! Moodle Desktop 3.6.1
| 14 May 2019
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.6.1_release_notes|Moodle Mobile 3.6.1]] plus the following desktop-specific improvement:
* It is now possible to enable the "Developer Tools" in the Desktop app using the same key combinations that the Chrome browser: "Control + Shift + I" (in MacOs is Command + Option + I).
|-
! Moodle Desktop 3.6.0
| 3 February 2019
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.6.0_release_notes|Moodle Mobile 3.6.0]]
|-
! Moodle Desktop 3.5.2
| 19 September 2018
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.5.2_release_notes|Moodle Mobile 3.5.2]]
|-
! Moodle Desktop 3.5.1
| 25 July 2018
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.5.1_release_notes|Moodle Mobile 3.5.1]]
|-
! Moodle Desktop 3.5.0
| -
|
-
| Skipped, see Moodle Desktop 3.5.1
|-
! Moodle Desktop 3.4.2
| 20 March 2018
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.4.2_release_notes|Moodle Mobile 3.4.2]]
|-
! Moodle Desktop 3.4.1
| 1 March 2018
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.4.1_release_notes|Moodle Mobile 3.4.1]]
|-
! Moodle Desktop 3.4.0
| 1 December 2017
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.4.0_release_notes|Moodle Mobile 3.4.0]]
|-
! Moodle Desktop 3.3.2
| 29 September 2017
|
* Windows 7, 8 and 10
* macOS
* Linux (32 and 64 bits)
| With all the features of [[Moodle_Mobile_3.3.2_release_notes|Moodle Mobile 3.3.2]] plus:
* New 32 bits version for Linux
|-
! Moodle Desktop 3.3.1
| 8 August 2017
|
* Windows 7, 8 and 10
* macOS
* Linux
| With all the features of [[Moodle_Mobile_3.3.1_release_notes|Moodle Mobile 3.3.1]] plus the following desktop-specific improvements:
* The app keeps the focus when re-opened via the status bar
* Scroll down on pages using a scroll wheel or trackpad gesture is now supported
|-
! Moodle Desktop 3.3.0
| 5 July 2017
| Windows 10
| With all the features of [[Moodle_Mobile_3.3.0_release_notes|Moodle Mobile 3.3.0]]
|}

== See also ==
* [[:en:Moodle Desktop|Moodle Desktop user documentation]]
* [[Moodle Mobile release notes]]

[[Category:Mobile]]

Moodle Mobile 1 release notes

2022-04-25T11:01:32Z

Pferre22:

[[Moodle Mobile release notes]] > {{FULLPAGENAME}}
=== Moodle Mobile 1.15 ===
29th May 2015

This will be the last release of the Moodle Mobile 1.x series.

Fixes and improvements:
* Prevent the user to log-in when file downloading is disabled in the Mobile service
* Content is now correctly displayed in Android 4.4.2
* The Moodle Mobile additional features plugin has been updated to support Moodle 2.9
* Prevent to process Moodle filters js code when rendering panels
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.15%22 Complete list of fixed issues in Moodle Mobile 1.15]
=== Moodle Mobile 1.14 ===
30th April 2015

New features and improvements:
* Student activity is showed in the Moodle site logs (requires Moodle 2.7 and onwards with the local_mobile plugin)
* Content in the app is processed through Moodle filters
* App updated to use new features and improvements in Moodle 2.9
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.14%22 Complete list of fixed issues in Moodle Mobile 1.14]
=== Moodle Mobile 1.13 ===
27th March 2015

New features:
* Teachers can view student's assignment submissions (both files and online-text) online and offline. (Requires Moodle 2.7)
* Files are opened in iOs using the Quick Look framework; from there they can be shared, printed or opened with a different application.
Improvements:
* The topic list for the front page now displays only one section.
Fixes:
* Javascript time function does not recognize some locales
* When scrolling down the contents page, some elements like pages or URLs are opened
* Incorrect function listed in the local_mobile db/services.php
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.13%22 Complete list of fixed issues in Moodle Mobile 1.13]
=== Moodle Mobile 1.12 ===
20th February 2015

New features:
* Any type of file can be uploaded to Moodle (in iOs using the "Open with" option; in Android via a new option in the Upload section)
* Group events are now displayed in the events list
* New reminder options for local notifications
* Removed unused permissions in Android; the app asks for less permissions during installation (yay!)
* Blocked users are listed in the contacts page
* You can block/unblock users in the messages option
Improvements:
* Local notifications: better synchronization with calendar events
* Notifications title in Android is now the site name (instead the Moodle Mobile word)
* Front page course is now supported
* When a site is deleted, the device is unregistered in your site
* Report a bug via email and "add as contact" options replaced
* Added extra debugging in order to warn developers that their Moodle custom version uses deprecated Web Services
* Documentation improved (general documentation, notifications, etc..)
* App description translated to new languages
Fixes:
* Fixed Iframe scrolling problems under iOS
* Fixed files not being deleted after being uploaded (video, audio and image)
* Fixed NW.js isFile missing function
* Fixed problem with uploading audio (NW.js version)
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.12%22 Complete list of fixed issues in Moodle Mobile 1.12]
=== Moodle Mobile 1.11 ===
16th January 2015

New features:
* Calendar integration with warning reminders as local notifications
* Sections summary is displayed in the course contents page
Improvements:
* The app uses non-deprecated web services if available
* Countries full name are displayed instead international short code
Fixed:
* Scrolling in the forum discussion screen open posts
* Page and resource contents opened inside an iframe don't open external links
* Resources with multiples files not available in offline mode (regression)
* New message text box incorrectly positioned
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.11%22 Complete list of fixed issues in Moodle Mobile 1.11]
=== Moodle Mobile 1.10 ===
26th December 2014

New features:
* Messages: new interface similar to Whatsapp/Telegram. You can view your recent conversations, search for contacts, add/remove contacts and view user profiles.
Improvements:
* New navigation system with improved headers. The main menu and submenus are now more consistent.
* Synchronization: You can choose to enable sync data only when on Wifi connection.
Fixes:
* Removing a site should delete all the entries in the database related to that site
* The user submenu styles has hard-coded colors
* App icon has large black outline on iOS8
* If a URL without the preceding www is specified then you get a very unhelpful error message
* Styling not applied when no notifications seen
* Label texts are shorten not truncating the last word
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.10%22 Complete list of fixed issues in Moodle Mobile 1.10]
=== Moodle Mobile 1.9 ===
28th November 2014

New features:
* New languages added: Bulgarian, Turkish and Chinese traditional
* Notifications: Forum notifications are more concise and include a link to open the discussion directly in the app.
* Grades: New "Show grades" button in the participants profile page to view that participant's grades (if you are allowed)
Improvements:
* General design: New main menu and back icons, courses menu section improved design.
* Forum design and usability: Discussions are now opened in a new page displaying all the posts expanded. Forum notifications open the discussion inside the app. Pressing the user name opens the user information page.
* Grades design and usability: Added missing icons, fixed background colours.
* Recent messages list design
Fixes:
* A course with empty folders displays errors
* The Mobile notifications server is smarter when using the smallmessage part of the notification
* A notification when no site is active will display a warning
* Users without permissions to view grades can't access the grades option
* Refresh button updates the current_site cache correctly
* Message sending blocks popups properly
* Labels doesn't display text properly filtered (TeX support missing)
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.9%22 Complete list of fixed issues in Moodle Mobile 1.9]
=== Moodle Mobile 1.8 ===
10th November 2014

New features:
* Support for Moodle 2.8
* Messages and notifications are separated in two different views
* HTML and Page resources are displayed using a viewer inside the app.
* If the user presses a phone notification, the app is opened displaying the complete notification
* Notification title is displayed in Android notifications bar
Improvements:
* Category and manual items are now displayed in the grades option
* Participants list is now paginated
* Downloaded files are opened automatically
* Downloaded files are named exactly as Moodle had them with UTF-8, white spaces etc.
* Keyboard is automatically displayed when a text field gains focus
Fixes:
* Interval time now decreases if a hook has a interval time lower than the defined in the app
* DirectorySize function now copes with empty subdirectories
Other:
* Donate to Moodle and help it grow! https://moodle.org/donations
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.8%22 Complete list of fixed issues in Moodle Mobile 1.8]

=== Moodle Mobile 1.7 ===
10th October 2014

New features:
* Forum activity support - users can read posts on and off-line, with messages synchronized periodically from the server (Note: requires the [[:en:Moodle_Mobile_additional_features|Moodle Mobile additional features add-on]])
* All files in a directory, page or file resource can be downloaded in just one tap
* Language translations updated
* New language: Persian
Improvements:
* Upgraded Cordova lib to 3.6.1
* New icon for activities only viewable in the Moodle site
* New loading icons
* In the calendar the panel on the right is not displayed in tablet view when there is no event
* Improved animation performance
Fixes:
* Complete support for iOS 8 devices
* Files inside folders in resources and directories are correctly downloaded
* Synchronization hooks for plugins fixed
* File names with German umlauts are correctly downloaded in the "My files" plugin
* Images are correctly stored for offline display in course labels
* File info pop-up is correctly displayed in folder and multiple files resources view
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.7%22 Complete list of fixed issues in Moodle Mobile 1.7]
=== Moodle Mobile 1.6.1 ===
8th September 2014 (Android, iOS, WP8, W8)

New features:
* Language translations updated
* New languages: Japanese, Russian and Hebrew
Improvements:
* Page titles displayed in “Tablet” view
* URL resources open in new browser (without requiring Moodle login)
* Files and resource contents visualization
Fixes:
* Invalid check of passwords incorrectly trimmed
* Files with spaces and German umlauts can’t be downloaded
* Login errors in sites nor returning release information
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.6.1%22 Complete list of fixed issues in Moodle Mobile 1.6.1]
=== Moodle Mobile 1.6 ===
7th August 2014 (Android, iOS, WP8, W8)

New features:
* View your total grade for each course
* New “My files” feature for browsing and downloading your private and course files
* New collapsible “Courses” menu for browsing courses
Improvements:
* Design polishing and optimization (notifications, calendar events and settings page)
* Grade retrieval optimized (faster with latest version of local_mobile plugin)
* Grade error handling improved
Fixes:
* Fixed display errors when browsing some types of activities
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.6%22 Complete list of fixed issues in Moodle Mobile 1.6]
=== Moodle Mobile 1.5 ===
18th July 2014 (Android and iOS)

New features:
* View your activity grades and outcomes (Requires configuration by the Moodle site administrator)
* New sign in and manage accounts page, quick access to all your sites
Improvements:
* The Site URL field now supports domains without the http/https protocol prefix
* Notifications page design improved
* Messages received can be replied in-line
* Refresh now updates all information related to the site
* The help link in the menu now points to documentation matching the current site version
* App design polished and optimized, improved support for site themes
Fixes:
* Menu scrolling bad positioning issue fixed
* Upload options are only available now if the service has the “Allow upload of files” setting enabled (for Moodle 2.6 and onwards)
Information for developers:
* New [[Moodle Mobile simulator]] for easier development
* New support for the Phonegap Developer App: [[Moodle Mobile Testing with Phonegap Developer app]]
* Themes creation documentation: [[Moodle Mobile Themes]]
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.5%22 Complete list of fixed issues in Moodle Mobile 1.5]
=== Moodle Mobile 1.4.4 ===
12th June 2014 (Android and iOS)

Added support for Moodle sites using SSO authentication methods like CAS or Shibboleth

Added support for the [[:en:Moodle_Mobile_additional_features|Moodle Mobile additional features add-on]]. Using that service all the app features are available for Moodle versions starting 2.4 (Including Push notifications)

New feature: Private messages and notifications retrieval

New language: Traditional Chinese

Relaxed validation rules for URLs so Moodle sites under private/internal networks can work

Improved support for remote styles

Improved offline and synchronization features

Fixed problem with photo uploading (it didn’t work correctly for some sites)

Fixed problem with settings plugins not begin displayed correctly in the settings menu

[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.4.4%22 Complete list of fixed issues in Moodle Mobile 1.4.4]
=== Moodle Mobile 1.4.3 ===
12th May 2014 (Android and iOS)

Android only: Added support for Push notifications (requires Moodle 2.7)

iOs only: Push notifications improved

New language: Arabic

German language updated

[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.4.3%22 Complete list of fixed issues in Moodle Mobile 1.4.3]
=== Moodle Mobile 1.4.2 ===
1st May 2014 (Android and iOS)

New language: German

Improved: Reduced the app size

Improved: Authentication security

Fixed: The app doesn't overlay the status bar any more

Fixed: Errors without proper information not displayed any more

Fixed: The app supports different locales

[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.4.2%22 Complete list of fixed issues in Moodle Mobile 1.4.2]
=== Moodle Mobile 1.4.1 ===
10th April 2014 (Android and iOS)

New feature: Video record and upload to your private files area in Moodle

Improved: Error and exception handling (no more white screens)

Fixed: Labels with images are correctly displayed

Fixed: The app can download files from nginx servers

[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.4.1%22 Complete list of fixed issues in Moodle Mobile 1.4.1]
=== Moodle Mobile 1.4 ===
3rd March 2014 (Android and iOS)

Notifications (iOS only): Supported by any Moodle 2.7 site or Moodle 2.6 with optional messaging output plugin

Calendar events (require Moodle 2.5.5 or Moodle 2.6.2 and onwards)

Alert when downloading too big files

Several bug fixes

New translations available:
* Mexican Spanish
* Euskara
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.4%22 Complete list of fixed issues in Moodle Mobile 1.4]
=== Moodle Mobile 1.3.4 ===
4th February 2014 (Android and iOS)

Contents/resources can be re-downloaded at any time

Application translated to these languages:
* Catalan
* Czech
* Spanish
* French
* Italian
* Hungarian
* Dutch
* Swedish
[https://tracker.moodle.org/issues/?jql=fixVersion%20%3D%20%221.3.4%22%20AND%20project%20%3D%20MOBILE Complete list of fixed issues in Moodle Mobile 1.3.4]
=== Moodle Mobile 1.3.3 ===
22th January (Android and iOS)
* New "About" option in Settings

* New "Space usage" option in Settings

* Initial support for node-webkit

* Fixed bug that broke the app in Android 4.4

* Fixed scrolling bug in contents and participants section for Android 2.1, 2.2 and 2.3
[https://tracker.moodle.org/issues/?jql=fixVersion%20%3D%20%221.3.3%22%20AND%20project%20%3D%20MOBILE Complete list of fixed issues in Moodle Mobile 1.3.3]
=== Moodle Mobile 1.3.2 ===
12th December (Android and iOS)
* Fixed bug that prevents files with white spaces in their name to be displayed
[https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20fixVersion%20%3D%20%221.3.2%22%20AND%20status%20%3D%20Open%20ORDER%20BY%20priority%20DESC Complete list of fixed issues in Moodle Mobile 1.3.2]
=== Moodle Mobile 1.3.1 ===
1st October (Android and iOS)
* Fixed the problem related to force log-in every time they opened the app (Android only)
* New quick logout option
* New splash screen
* Small fixes related to design
* Security fixes related to sites with certificates
[https://tracker.moodle.org/issues/?jql=fixVersion%20%3D%20%221.3.1%22%20AND%20project%20%3D%20MOBILE Complete list of fixed issues in Moodle Mobile 1.3.1]
=== Moodle Mobile 1.3 ===
24th September (Android and iOS)

[[Moodle Mobile 1.3 Release Notes]]
=== Moodle Mobile 1.2.2 ===
27 May 2013 Android

12 September 2013 iOS

Security release:
* MOBILE-413 bug fixed

* Improved security of user tokens
=== Moodle Mobile 1.2.1 ===
15 April 2013 iOS

8 April 2013 Android

We’ve called it version 1.2 because the feature set is inherited from the deprecated iOS-only app [[Mobile app | “My Moodle”]] which was version 1.1.

Thanks to all the developers who’ve worked on this version of the app: Juan Leyva, Jerome Mouneyrac, Barbara Ramiro, Martin Dougiamas and Josep Gifreu.

The new app has been designed as a platform with the following strengths:
* It is secure
* It can work offline
* It can support notifications (coming soon)
* It can be branded and expanded by an institution
* It makes some Moodle operations faster and more convenient
''' Features '''
* Responsive design for phone and tablets
* Upload a picture into your private file area
* Record an audio file and upload it into your private file area
* Send a private message to a course participant (can be done offline)
* Take a personal note about a course participant (can be done offline)
* Add a course participant to your phone contact
* Call a course participant touching the phone number
* Locate a course participant address on Google map
* Download and view some resources
* Quick access to your course contents
* Remote translation (see bellow)
* Remote layout/style customization (see bellow)
''' Documentation '''

[[:en:Moodle Mobile app|Moodle Mobile app]]

''' Requirements '''

Moodle 2.4

'''Download links:'''

Apps are available in Google Play and also Apple Store. You can install the app directly from your Mobile device, search for "Moodle Mobile" the author/owner must be "Moodle Pty Ltd"
* Android: https://play.google.com/store/apps/details?id=com.moodle.moodlemobile

* iOS: https://itunes.apple.com/es/app/moodle-mobile/id633359593

[[Category:Mobile]]

Moodle App Plugins Development Guide

2022-04-25T08:31:03Z

Pferre22: /* core-format-text */

{{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-label><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-label>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<ion-label>
<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" slot="start"></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</ion-label>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<ion-label><p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p></ion-label>
</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>
<ion-label>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-label>
</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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons section]].
** <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> — Path to the module icon. After Moodle app 4.0, this icon is only used as a fallback, the app will always try to use the theme icon so themes can override icons in the app.
** <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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons section]].
** <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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons 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 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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons section]].
* <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>.

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>
==== Using 'font' icons with <code>ion-icon</code>====
Font icons are widely used on the app and Moodle LMS website. In order to support [https://fontawesome.com/v5/search?m=free font awesome icons]. We've added a directive that uses prefixes on the <code>name</code> attribute to use different font icons.
* Name prefixed with <code>fas-</code> or <code>fa-</code> will use [https://fontawesome.com/v5/search?m=free&s=solid Font awesome solid] library.
* Name prefixed with <code>far-</code> will use [https://fontawesome.com/v5/search?m=free&s=regular Font awesome regular] library.
* Name prefixed with <code>fab-</code> will use [https://fontawesome.com/v5/search?m=free&s=brands Font awesome brands] library (But only a few are supported and we discourage to use them).
* Name prefixed with <code>moodle-</code> will use some svg icons [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/moodle imported from Moodle LMS].
* Name prefixed with <code>fam-</code> will use [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/font-awesome customized font awesome icons].
* If the prefix is not found or not valid, the app will search the icon name on the [https://ionic.io/ionicons ionicons library].

Example of usage to show icon "pizza-slice" from font-awesome regular library:
<syntaxhighlight lang="html">
<ion-icon name="fas-pizza-slice"></ion-icon>
</syntaxhighlight>
We encourage the use of font-awesome icons to match the appearance from the LMS website version.
===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-label><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-label>
</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-25T08:26:45Z

Pferre22: /* Options only for AddonMessageOutputDelegate */

{{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-label><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-label>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<ion-label>
<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" slot="start"></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</ion-label>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<ion-label><p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p></ion-label>
</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>
<ion-label>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-label>
</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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons section]].
** <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> — Path to the module icon. After Moodle app 4.0, this icon is only used as a fallback, the app will always try to use the theme icon so themes can override icons in the app.
** <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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons section]].
** <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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons 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 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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons section]].
* <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>
==== Using 'font' icons with <code>ion-icon</code>====
Font icons are widely used on the app and Moodle LMS website. In order to support [https://fontawesome.com/v5/search?m=free font awesome icons]. We've added a directive that uses prefixes on the <code>name</code> attribute to use different font icons.
* Name prefixed with <code>fas-</code> or <code>fa-</code> will use [https://fontawesome.com/v5/search?m=free&s=solid Font awesome solid] library.
* Name prefixed with <code>far-</code> will use [https://fontawesome.com/v5/search?m=free&s=regular Font awesome regular] library.
* Name prefixed with <code>fab-</code> will use [https://fontawesome.com/v5/search?m=free&s=brands Font awesome brands] library (But only a few are supported and we discourage to use them).
* Name prefixed with <code>moodle-</code> will use some svg icons [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/moodle imported from Moodle LMS].
* Name prefixed with <code>fam-</code> will use [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/font-awesome customized font awesome icons].
* If the prefix is not found or not valid, the app will search the icon name on the [https://ionic.io/ionicons ionicons library].

Example of usage to show icon "pizza-slice" from font-awesome regular library:
<syntaxhighlight lang="html">
<ion-icon name="fas-pizza-slice"></ion-icon>
</syntaxhighlight>
We encourage the use of font-awesome icons to match the appearance from the LMS website version.
===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-label><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-label>
</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-25T08:24:11Z

Pferre22: /* Options only for CoreSettingsDelegate */

{{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-label><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-label>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<ion-label>
<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" slot="start"></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</ion-label>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<ion-label><p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p></ion-label>
</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>
<ion-label>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-label>
</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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons section]].
** <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> — Path to the module icon. After Moodle app 4.0, this icon is only used as a fallback, the app will always try to use the theme icon so themes can override icons in the app.
** <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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons section]].
** <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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons 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 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>

==== Using 'font' icons with <code>ion-icon</code>====

Font icons are widely used on the app and Moodle LMS website. In order to support [https://fontawesome.com/v5/search?m=free font awesome icons]. We've added a directive that uses prefixes on the <code>name</code> attribute to use different font icons.
* Name prefixed with <code>fas-</code> or <code>fa-</code> will use [https://fontawesome.com/v5/search?m=free&s=solid Font awesome solid] library.
* Name prefixed with <code>far-</code> will use [https://fontawesome.com/v5/search?m=free&s=regular Font awesome regular] library.
* Name prefixed with <code>fab-</code> will use [https://fontawesome.com/v5/search?m=free&s=brands Font awesome brands] library (But only a few are supported and we discourage to use them).
* Name prefixed with <code>moodle-</code> will use some svg icons [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/moodle imported from Moodle LMS].
* Name prefixed with <code>fam-</code> will use [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/font-awesome customized font awesome icons].
* If the prefix is not found or not valid, the app will search the icon name on the [https://ionic.io/ionicons ionicons library].

Example of usage to show icon "pizza-slice" from font-awesome regular library:
<syntaxhighlight lang="html">
<ion-icon name="fas-pizza-slice"></ion-icon>
</syntaxhighlight>

We encourage the use of font-awesome icons to match the appearance from the LMS website version.

===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-25T08:23:43Z

Pferre22: /* Options only for CoreUserDelegate */

{{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-label><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-label>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<ion-label>
<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" slot="start"></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</ion-label>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<ion-label><p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p></ion-label>
</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>
<ion-label>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-label>
</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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons section]].
** <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> — Path to the module icon. After Moodle app 4.0, this icon is only used as a fallback, the app will always try to use the theme icon so themes can override icons in the app.
** <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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons section]].
** <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>

==== Using 'font' icons with <code>ion-icon</code>====

Font icons are widely used on the app and Moodle LMS website. In order to support [https://fontawesome.com/v5/search?m=free font awesome icons]. We've added a directive that uses prefixes on the <code>name</code> attribute to use different font icons.
* Name prefixed with <code>fas-</code> or <code>fa-</code> will use [https://fontawesome.com/v5/search?m=free&s=solid Font awesome solid] library.
* Name prefixed with <code>far-</code> will use [https://fontawesome.com/v5/search?m=free&s=regular Font awesome regular] library.
* Name prefixed with <code>fab-</code> will use [https://fontawesome.com/v5/search?m=free&s=brands Font awesome brands] library (But only a few are supported and we discourage to use them).
* Name prefixed with <code>moodle-</code> will use some svg icons [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/moodle imported from Moodle LMS].
* Name prefixed with <code>fam-</code> will use [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/font-awesome customized font awesome icons].
* If the prefix is not found or not valid, the app will search the icon name on the [https://ionic.io/ionicons ionicons library].

Example of usage to show icon "pizza-slice" from font-awesome regular library:
<syntaxhighlight lang="html">
<ion-icon name="fas-pizza-slice"></ion-icon>
</syntaxhighlight>

We encourage the use of font-awesome icons to match the appearance from the LMS website version.

===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-25T08:20:45Z

Pferre22: /* Options only for CoreMainMenuDelegate */

{{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-label><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-label>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<ion-label>
<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" slot="start"></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</ion-label>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<ion-label><p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p></ion-label>
</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>
<ion-label>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-label>
</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. [[Moodle_App_Plugins_Development_Guide#Using_.27font.27_icons_with_ion-icon|See icons section]].
** <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> — Path to the module icon. After Moodle app 4.0, this icon is only used as a fallback, the app will always try to use the theme icon so themes can override icons in the app.
** <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>

==== Using 'font' icons with <code>ion-icon</code>====

Font icons are widely used on the app and Moodle LMS website. In order to support [https://fontawesome.com/v5/search?m=free font awesome icons]. We've added a directive that uses prefixes on the <code>name</code> attribute to use different font icons.
* Name prefixed with <code>fas-</code> or <code>fa-</code> will use [https://fontawesome.com/v5/search?m=free&s=solid Font awesome solid] library.
* Name prefixed with <code>far-</code> will use [https://fontawesome.com/v5/search?m=free&s=regular Font awesome regular] library.
* Name prefixed with <code>fab-</code> will use [https://fontawesome.com/v5/search?m=free&s=brands Font awesome brands] library (But only a few are supported and we discourage to use them).
* Name prefixed with <code>moodle-</code> will use some svg icons [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/moodle imported from Moodle LMS].
* Name prefixed with <code>fam-</code> will use [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/font-awesome customized font awesome icons].
* If the prefix is not found or not valid, the app will search the icon name on the [https://ionic.io/ionicons ionicons library].

Example of usage to show icon "pizza-slice" from font-awesome regular library:
<syntaxhighlight lang="html">
<ion-icon name="fas-pizza-slice"></ion-icon>
</syntaxhighlight>

We encourage the use of font-awesome icons to match the appearance from the LMS website version.

===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-25T08:18:21Z

Pferre22: /* Step 4. Adding an additional page */

{{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-label><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-label>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<ion-label>
<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" slot="start"></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</ion-label>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<ion-label><p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p></ion-label>
</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>
<ion-label>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-label>
</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> — Path to the module icon. After Moodle app 4.0, this icon is only used as a fallback, the app will always try to use the theme icon so themes can override icons in the app.
** <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>

==== Using 'font' icons with <code>ion-icon</code>====

Font icons are widely used on the app and Moodle LMS website. In order to support [https://fontawesome.com/v5/search?m=free font awesome icons]. We've added a directive that uses prefixes on the <code>name</code> attribute to use different font icons.
* Name prefixed with <code>fas-</code> or <code>fa-</code> will use [https://fontawesome.com/v5/search?m=free&s=solid Font awesome solid] library.
* Name prefixed with <code>far-</code> will use [https://fontawesome.com/v5/search?m=free&s=regular Font awesome regular] library.
* Name prefixed with <code>fab-</code> will use [https://fontawesome.com/v5/search?m=free&s=brands Font awesome brands] library (But only a few are supported and we discourage to use them).
* Name prefixed with <code>moodle-</code> will use some svg icons [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/moodle imported from Moodle LMS].
* Name prefixed with <code>fam-</code> will use [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/font-awesome customized font awesome icons].
* If the prefix is not found or not valid, the app will search the icon name on the [https://ionic.io/ionicons ionicons library].

Example of usage to show icon "pizza-slice" from font-awesome regular library:
<syntaxhighlight lang="html">
<ion-icon name="fas-pizza-slice"></ion-icon>
</syntaxhighlight>

We encourage the use of font-awesome icons to match the appearance from the LMS website version.

===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-25T08:17:33Z

Pferre22: /* Options only for CoreCourseModuleDelegate */

{{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-label><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-label>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<ion-label>
<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" slot="start"></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</ion-label>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<ion-label><p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p></ion-label>
</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> — Path to the module icon. After Moodle app 4.0, this icon is only used as a fallback, the app will always try to use the theme icon so themes can override icons in the app.
** <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>

==== Using 'font' icons with <code>ion-icon</code>====

Font icons are widely used on the app and Moodle LMS website. In order to support [https://fontawesome.com/v5/search?m=free font awesome icons]. We've added a directive that uses prefixes on the <code>name</code> attribute to use different font icons.
* Name prefixed with <code>fas-</code> or <code>fa-</code> will use [https://fontawesome.com/v5/search?m=free&s=solid Font awesome solid] library.
* Name prefixed with <code>far-</code> will use [https://fontawesome.com/v5/search?m=free&s=regular Font awesome regular] library.
* Name prefixed with <code>fab-</code> will use [https://fontawesome.com/v5/search?m=free&s=brands Font awesome brands] library (But only a few are supported and we discourage to use them).
* Name prefixed with <code>moodle-</code> will use some svg icons [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/moodle imported from Moodle LMS].
* Name prefixed with <code>fam-</code> will use [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/font-awesome customized font awesome icons].
* If the prefix is not found or not valid, the app will search the icon name on the [https://ionic.io/ionicons ionicons library].

Example of usage to show icon "pizza-slice" from font-awesome regular library:
<syntaxhighlight lang="html">
<ion-icon name="fas-pizza-slice"></ion-icon>
</syntaxhighlight>

We encourage the use of font-awesome icons to match the appearance from the LMS website version.

===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-25T08:16:34Z

Pferre22: /* Step 3. Creating the template for the main function */

{{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-label><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-label>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<ion-label>
<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" slot="start"></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</ion-button>
</ion-label>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<ion-label><p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p></ion-label>
</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>

==== Using 'font' icons with <code>ion-icon</code>====

Font icons are widely used on the app and Moodle LMS website. In order to support [https://fontawesome.com/v5/search?m=free font awesome icons]. We've added a directive that uses prefixes on the <code>name</code> attribute to use different font icons.
* Name prefixed with <code>fas-</code> or <code>fa-</code> will use [https://fontawesome.com/v5/search?m=free&s=solid Font awesome solid] library.
* Name prefixed with <code>far-</code> will use [https://fontawesome.com/v5/search?m=free&s=regular Font awesome regular] library.
* Name prefixed with <code>fab-</code> will use [https://fontawesome.com/v5/search?m=free&s=brands Font awesome brands] library (But only a few are supported and we discourage to use them).
* Name prefixed with <code>moodle-</code> will use some svg icons [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/moodle imported from Moodle LMS].
* Name prefixed with <code>fam-</code> will use [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/font-awesome customized font awesome icons].
* If the prefix is not found or not valid, the app will search the icon name on the [https://ionic.io/ionicons ionicons library].

Example of usage to show icon "pizza-slice" from font-awesome regular library:
<syntaxhighlight lang="html">
<ion-icon name="fas-pizza-slice"></ion-icon>
</syntaxhighlight>

We encourage the use of font-awesome icons to match the appearance from the LMS website version.

===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-25T08:11:42Z

Pferre22: /* Using icons */

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

==== Using 'font' icons with <code>ion-icon</code>====

Font icons are widely used on the app and Moodle LMS website. In order to support [https://fontawesome.com/v5/search?m=free font awesome icons]. We've added a directive that uses prefixes on the <code>name</code> attribute to use different font icons.
* Name prefixed with <code>fas-</code> or <code>fa-</code> will use [https://fontawesome.com/v5/search?m=free&s=solid Font awesome solid] library.
* Name prefixed with <code>far-</code> will use [https://fontawesome.com/v5/search?m=free&s=regular Font awesome regular] library.
* Name prefixed with <code>fab-</code> will use [https://fontawesome.com/v5/search?m=free&s=brands Font awesome brands] library (But only a few are supported and we discourage to use them).
* Name prefixed with <code>moodle-</code> will use some svg icons [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/moodle imported from Moodle LMS].
* Name prefixed with <code>fam-</code> will use [https://github.com/moodlehq/moodleapp/tree/master/src/assets/fonts/moodle/font-awesome customized font awesome icons].
* If the prefix is not found or not valid, the app will search the icon name on the [https://ionic.io/ionicons ionicons library].

Example of usage to show icon "pizza-slice" from font-awesome regular library:
<syntaxhighlight lang="html">
<ion-icon name="fas-pizza-slice"></ion-icon>
</syntaxhighlight>

We encourage the use of font-awesome icons to match the appearance from the LMS website version.

===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-25T07:58:05Z

Pferre22: /* Custom core components and directives */

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

==== Using icons ====

===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 Release Process

2022-04-25T07:51:08Z

Pferre22: /* The following days */

== Two weeks before (Code freeze) ==
{| class="table table-striped table-bordered"
|-
! style="width:20px" | #
! Task
! style="width:12%" | Responsibility
|-
| 1.
| Create an issue in the tracker for the release, like: MOBILE-1248
| Integration Lead
|-
| 2.
| Force an update of the [https://moodle.org/plugins/view.php?id=997 local_moodlemobileapp] plugin (as release candidate) with new strings in moodle.org/plugins (only for Moodle version 2.6).
| Dev
|-
| 3.
| Ask someone from sites or community team to review the new English strings.
| Community or Sites team
|-
| 4.
| Announce in the moodletranslation forums the new strings available: https://lang.moodle.org/mod/forum/view.php?id=5. This will allow translators to add the new strings during the days prior to the release.
| Integration Lead
|-
| 5.
| Add the release notes in the release issue created (search for the [https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20labels%20%3D%20release_notes release_notes tag]). Ask someone from the documentation team or Martin to review the release notes.
| Integration Lead
|-
| 6.
| Contact the marketing team announcing the new release and highlights.
| Integration Lead
|-
| 7.
| Add new QA tests to the “Testing cases” document. New QA tests should be labeled with [https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20resolution%20in%20(Unresolved%2C%20Fixed)%20AND%20labels%20%3D%20qa_test_required%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC qa_test_required]. Remove that label once are added to the document.
| Tester
|-
| 8.
| Run npm audit to ensure all the dependencies are OK.
| Developer
|-
| 9.
| Freeze Cordova plugins and Javascript libraries versions (node modules) in the integration branch.
| Developer
|-
| 10.
| '''Start testing'''
| Tester
|}
== The release day ==
{| class="table table-striped table-bordered"
|-
! style="width:20px" | #
! Task
! style="width:12%" | Responsibility
|-
| 1.
| Fix the version name in integration/config.xml, integration/package.json and integration:src/config.json (remove the -dev).
| Integration Lead
|-
| 2.
| Integrate the [https://github.com/moodlehq/moodleapp/compare/master...integration integration branch onto the master one].
| Integration Lead
|-
| 3.
| Do some testing with the production builds before sending the application to the stores (overall testing to see that nothing is broken because of the branch merge done in step 2):
* Correct definitive version name displayed (and commit)
* AOT compiling worked
* Language strings synchronised from lang.moodle.net
* New language packs added
| All the team
|-
| 4.
| Send the applications to the stores for review.
| Integration Lead
|-
| 5.
| Create a TAG/Release in github ([https://github.com/moodlehq/moodleapp/releases moodlehq/moodleapp]) with the version number.
| Integration Lead
|-
| 6.
| Mark the issue and the [https://tracker.moodle.org/projects/MOBILE?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page version] as released in the tracker.
| Integration Lead
|-
| 7.
| Update release notes [[Moodle_Mobile_Release_Notes]] .
| Integration Lead
|}
== The following days ==
{| class="table table-striped table-bordered"
|-
! style="width:20px" | #
! Task
! style="width:12%" | Responsibility
|-
| 1.
| Social media announcements (Forum and Twitter).
| All the team & Marketing team
|-
| 2.
| Post in moodle.org/news.
| Team Lead
|-
| 3.
| Review the users and developers documentation (check that everything is in order). Review the [https://tracker.moodle.org/issues/?jql=project%20%3D%20MOBILE%20AND%20labels%20in%20%28docs_required%2C%20dev_docs_required%29 docs_required and dev_docs_required_tags]. Review the [https://docs.moodle.org/en/Moodle_Mobile_features Mobile features wiki documentation].
| All the team
|-
| 4.
| Delete the integration and desktop branches and create it again based on master.
| Team Lead
|-
| 5.
| Bump version numbers in the following files in the integration branch: config.xml, src/config.json (appending a -dev to the versionname field to indicate that is a development version), package.json (including mac->bundleVersion) and desktop/assets/windows/AppXManifest.xml.
| Integration Lead
|-
| 6.
| Unfreeze Cordova plugins and Javascript libraries versions (node modules).
| Developer
|-
| 7.
| Check that the [https://cloud.docker.com/u/moodlehq/repository/docker/moodlehq/moodleapp/general Docker image] for the new version was successfully built.
| Integration Lead
|-
| 8.
| Update of the [https://moodle.org/plugins/view.php?id=997 local_moodlemobileapp] plugin (as final release) in moodle.org/plugins.
| Developer
|}
== See also ==
* [[Moodle App Release Notes]]
[[Category:Processes]]
[[Category:Mobile]]
{{DISPLAYTITLE:Moodle app release process}}

Moodle Mobile 1 Developing a plugin tutorial

2022-04-07T12:57:18Z

Pferre22: Remove legacy links

{{Moodle Mobile 1}}
== Introduction ==
This tutorial describes all the steps needed for developing a plugin for the MoodleMobile app.

In this tutorial we make the following assumptions:
* You have a medium/good skills/understand of Javascript, PHP and Moodle architecture
* You know what a Web Service is and how it works in Moodle
* The plugin you are going to develop requires a Web Service in your Moodle installation to work
'''Notice that neither the moodle plugin code and the moodle mobile plugin code are suitable for production environments'''

There is a second part of this tutorial where we extend the current WebServices and create a new "forums" plugin, see [[Moodle Mobile Developing a plugin tutorial part 2]]
== Plugin spec ==
We want to develop a "grades" plugin that will display the current user grades for all the gradable activities in a course the user is enroll in.

A screenshot of the desired result:

[[File:MoodleMobileTutorial01.png]]

As you can see there is a new menu called "Grades" that displays a page in the middle panel showing all the course activities. When we click in an activity, the right panel shows the grade / maximum grade for the current user.

In order to achieve this we will have to develop:
* A plugin for Moodle containing a new Web Service that returns grades and..
* A MoodleMobile plugin
== Steps ==
=== Set up your development environment ===
Clone or fork the official git repository [https://github.com/moodlehq/moodlemobile] in a local directory.

Set up your development browser, see [[Moodle_Mobile]], I mainly use the Google Chrome browser.
=== Set up your Moodle installation ===
Enable debugging, disable caches, etc... the typical settings for developing.

Enable the Web Services and also the protocols you are going to use for testing and developing (REST is mandatory). See [[Web Services]] documentation.

Enable the Mobile Service

Enable the moodle/webservice:createtoken capability for the Authenticated User Role at System Context
=== Develop the Moodle local/mod/block/... plugin ===
You can find the full source code here:
https://github.com/cvaconsulting/moodle-local_custommm

In this case we've developed a local plugin that contains a Web Service that returns grades as described here: https://tracker.moodle.org/browse/MDL-30085

Notice that my version has some differences with the previous mentioned one. I have fixed some small bugs and changed some parameters.
=== Test your Web Services using a demo client ===
Before continuing you must test that your Web Service works, the local plugin contains a demo REST client, see:

https://github.com/cvaconsulting/moodle-local_custommm/blob/master/client/client.php
=== Create your custom Service ===
A service is a set of functions for an specific purpose. Since Moodle 2.1 there is a pre-built service that contains all the functions needed for the official mobile app.

This service cannot be edited for adding new functions so we don't have a simple way for make available our new Web Service function to the mobile app.

The only way for fix this is creating a new Service in Moodle, and configuring our app for pointing to this new service.

There are two ways of creating a Service in Moodle:
* Using a db/services.php in your plugin as mentioned here: [[External services description]]

* Creating the service in your Moodle installation using the forms in Admin > Plugins > Web Services > External Services
In this case we've created the service using the Moodle forms because it gives more flexibility in some aspects, there is a big impediment, due to https://tracker.moodle.org/browse/MDL-29807 in order to add a shortname for the new Service, we have to edit manually the Moodle database for adding the shortname in the dbprefix_external_services table

[[File:MoodleMobileTutorial02.png]]

When creating, the flats "Can download files" and "Enabled" must be checked.
=== Set up your MoodleMobile client ===
The most important change you have to do is edit the config.json file and change the wsservice parameter in order to point to the shortname of the Service you created before.

You have to add also the name of the plugin you are developing at the final of the plugins parameter:

"plugins" : ["notifications", "upload", "contents", "participants", "addcontact", "addnote", "sendmessage", "grades"],

Notice that, for avoid errors, this last change should be done once the file plugins/grades/main.js file exists
=== Develop the MoodleMobile plugin ===
The full source code can be found here:

https://github.com/cvaconsulting/moodlemobile-grades

https://github.com/cvaconsulting/moodlemobile-grades/blob/master/lang/en.json - Contains the language strings, the string "pluginPLUGINname" is mandatory

https://github.com/cvaconsulting/moodlemobile-grades/blob/master/icon.png - The plugin icon

https://github.com/cvaconsulting/moodlemobile-grades/blob/master/activities.html - The template for the activities list (center panel)

https://github.com/cvaconsulting/moodlemobile-grades/blob/master/activitygrade.html - The template for showing the grade for an activity (right panel)

https://github.com/cvaconsulting/moodlemobile-grades/blob/master/main.js - The plugin's main code

Bellow, I summarize the most important parts of the code (always parts of the main.js file):
<syntaxhighlight lang="javascript">

var templates = [
"root/externallib/text!root/plugins/grades/activities.html",
"root/externallib/text!root/plugins/grades/activitygrade.html",
"root/externallib/text!root/plugins/grades/lang/en.json"
];

define(templates,function (activities, activityGrade, langStrings) {
var plugin = {
settings: {
name: "grades",
type: "course",
menuURL: "#course/grades/",
lang: {
component: "local_custommm",
strings: langStrings
}
},

</syntaxhighlight>
Notice that we required three files, the two templates (.html) and the .json file that contains the lang strings.

In the plugin.settings structure, we define the lant attribute that contains two very important attributes:
* Component: It must refer to the Moodle component linked to this plugin
* strings: The lang strings in .json format (plain text). As you can see, with this line we are populating the plugin.settings.lang.strings var withe the contents of the lang/en.json files
<syntaxhighlight lang="javascript">

viewActivities: function(courseId) {

MM.panels.showLoading('center');

if (MM.deviceType == "tablet") {
MM.panels.html('right', '');
}

var data = {
"options[0][name]" : "",
"options[0][value]" : ""
};
data.courseid = courseId;

MM.moodleWSCall('core_course_get_contents', data, function(contents) {
var course = MM.db.get("courses", MM.config.current_site.id + "-" + courseId);

var tpl = {
sections: contents,
course: course.toJSON() // Convert a model to a plain javascript object.
}
var html = MM.tpl.render(MM.plugins.grades.templates.activities.html, tpl);
MM.panels.show("center", html);
});
},

</syntaxhighlight>
The viewActivities is the function that displays in the center panel the list of activities inside a course, as you can see the code is pretty simple.
* We call to the core_course_get_contents Web Service that returns all the activities and resources inside a course
* We render the template that will iterate over the sections and activities displaying the links to specifics activities
<syntaxhighlight lang="javascript">
viewActivityGrade: function(activityName, courseId, modName, cmId) {

if (MM.deviceType == "tablet") {
MM.panels.showLoading('right');
}

var data = {
"grades[courseid]" : courseId,
"grades[component]" : "mod_" + modName,
"grades[cmid]" : cmId,
"grades[userids][0]" : MM.config.current_site.userid
};

MM.moodleWSCall('local_custommm_get_grades', data, function(contents) {
var course = MM.db.get("courses", MM.config.current_site.id + "-" + courseId);

var grade= MM.lang.s("nogrades", "grades");

if(contents.items[0]) {
grade = contents.items[0]["grades"][0]["str_long_grade"];
}

var tpl = {
activityName: activityName,
sections: contents,
finalGrade: grade,
course: course.toJSON(), // Convert a model to a plain javascript object.
items: contents
}
var html = MM.tpl.render(MM.plugins.grades.templates.activityGrade.html, tpl);
MM.panels.show("right", html);
if (MM.deviceType == "tablet" && contents.length > 0) {
// First section.
MM.plugins.contents.viewCourseContentsSection(courseId, 0);
}
});
},
</syntaxhighlight>
This function gets and displays the grade for the selected activity in the centered panel.

We just call to the Web Service we developed and parse the result, if nothing is returned we display a generic message indicating that there is no grades information for the activity.
If a grades full structure is returned, we return the first grade for the first grade items (as Moodle usually does) that corresponds to the user grade for the activity

Notice that:
* Some activities, like workshop, returns two different grades items (teacher and peer grades). The example doesn't implement any logic for this case.
* Some activities may return outcomes. The example doesn't implement any logic for this case.
* The rest grade information (grade min, grade max, feedback) is also covered by this example.
=== Deliver your plugin ===
Android: Package your plugin using ''PhoneGap build''

iOs: Further instructions soon
== See also ==
[[Moodle Mobile Developing a plugin tutorial part 2]]

Moodle Mobile 1 Customization

2022-04-07T12:55:50Z

Pferre22: Remove legacy links

{{Moodle Mobile 1}}
== Overview ==
In this document are described the general steps for building your custom Mobile app.

You can find a step by step guide of how to create a custom version of the app here: http://es.slideshare.net/juanleyva/creating-a-custom-moodle-mobile-app-moodle-moot-spain-2014
== Creating your custom application ==
Remember that if you only want to change the global styles of the app, you can use an extra CSS file in your Moodle installation without needing to recompile the app.
=== Basic custom settings ===
In your Moodle installation you can specify a extra CSS file in the Mobile settings section

You can edit the config.json file for:
- Adding a default language
- Add some presets in the login screen (url and username) pointing to your installation
=== Development environment ===
See [[#Testing_and_developing]]

It is recommended that you have a local web server (app and moodle installation under localhost or the same local domain).

You will need:
* A Moodle installation with Web Services (REST) enabled - see [[Web services]] documentation
:* Administration -> Plugins -> Web Services -> External Services -> Enable mobile web service

:* Administration -> Plugins -> Web Services -> Protocols -> Enable REST

:* Administration -> Users -> Permission -> Define roles -> Edit the Authenticated user role -> Allow webservice/rest:use
* A local copy of the Mobile HTML5 App with the Debugging options Enabled (https://github.com/moodlehq/moodlemobile)
=== Web Services Development ===
In most cases your plugin/s will need Web Services to get data from your Moodle installation. It is recommended that you first develop the Web Services that you will need (see [[Web Services]]).
* Create a local plugin in Moodle for adding the extra Web Services you need and also your plugin's lang files (Local WS plugin template: https://moodle.org/plugins/view.php?plugin=local_wstemplate)

* Create a new External Service in your Moodle installation, adding a services.php file in your new local plugin or creating manually the service in your Moodle installation.(Plugins -> Web Services) See [[External services description]] for more info. Remember the key name of the service, because you will need it later.
=== Moodle Mobile Plugin Development ===
See [[Moodle Mobile 1 Plugins Development]] and [[Moodle Mobile 1 Developing a plugin tutorial]]

For developing the plugin you need:
* Edit the /config.json file to:
:* Add the extra plugins you implement
:* Indicate the WS service name you are going to use in your Moodle installation (Remember, that you need to create a WS Service indicating the functions available for your custom app)
:* Add your custom default lang file (es, ca, fr ...) (the language file must exists in the app's lang/ folder)
:* Change the app login form presets
* Add your own css files, custom images, etc..
=== Building ===
There are three options for building the app, aka compile it to different devices:

'''Phonegap Build'''

''Phonegap Build'' is an online service that let you to build the app automatically for different platforms. The main advantage is that simplify a lot the process of building.

You just put your customizations in a github account and Phonegaps automatically build the app for different platforms pulling your github code.

Notice that the free version is for open repositories, but you can use the non-free version for private repositories.

'''Phonegap CLI'''

You can build also using the Phonegap CLI interface, it requires to install the different Platform SDK / tools but the build process is simpler.

Once installed the environment, you need to deploy in your project/www folder the app code

'''Platform SDK'''

See [[Moodle Mobile Building the app for Android]] or [[Moodle Mobile Building the app for iOS]] (These articles may be obsolete)

'''Automatic build system'''

See [[Moodle Mobile Automatic Building System]] for some instructions for building an automatic building system initially for Android.
== Testing and developing ==
=== Chromium or Google Chrome browser ===
See [[Moodle Mobile development using Chrome or Chromium]]
=== Ripple ===
Requirements: Google Chrome browser + Ripple mobile environment emulator plugin (http://ripple.tinyhippos.com/)

You must run Google Chrome in Unsafe mode adding this param:
--allow-file-access-from-files
IMPORTANT: I strongly recommend you create a new link or application launch called "Google Unsafe" and use it only for testing the app.
"Path to chrome\chrome.exe" --allow-file-access-from-files
Open the index.html file in the Google Chrome unsafe and click on the Ripple icon to activate the emulator.

Once opened in the Ripple settings block, change Cross Domain Proxy to Disabled.

Please note that some functionalities (camera, audio recording, contact) will not work in the emulator.
=== Platform SDK ===
Install the Android or iPhone SDK.
=== Debugging styles or running a remote Console ===
You can use Safari or Google Chrome developer tools for debugging (console) and changing the CSS styles in live:

https://developer.chrome.com/devtools/docs/remote-debugging

http://phonegap-tips.com/articles/debugging-ios-phonegap-apps-with-safaris-web-inspector.html

=== Local web server ===
If you deploy the html files in a server under the same domain that the Moodle you are going to connect to you can test the application without emulator or changing the Security settings of your browser.

In other words

Your Moodle at http://myhost.com/moodle24

Your app at http://myhost.com/moodlemobile/

or

Your Moodle at http://localhost/moodle24

Your app at http://localhost/moodlemobile/

Note that the mobile - related modules will not work.
== See also ==
[http://es.slideshare.net/juanleyva/creating-a-custom-moodle-mobile-app-moodle-moot-spain-2014 Creating a custom Moodle Mobile app - MoodleMoot Spain 2014]

Moodle Mobile 2 (Ionic 1) Customization

2022-04-07T12:54:12Z

Pferre22: /* Building */

{{Moodle Mobile 2 (Ionic 1)}}
IMPORTANT: This documentation will be obsolete in May 2018, please [https://moodle.org/mod/forum/discuss.php?d=360412 read this announcement].
== Overview ==
Moodle Mobile can be customized in different ways:
* Changing the app appearance for your site.
* Creating a set of remote add-ons in order to add additional functionalities to the app.
* Creating a custom application (with your custom name and icon) based on the Moodle Mobile code.
* Configuring how the app should work via Moodle site settings.
With the first two options you are not required to compile or build your custom application, with the third one you are required to compile and publish your custom app in the stores.
== Changing the app appearance for your site ==
The Mobile app can retrieve your custom styles from your Moodle site. Since is an HTML5 app, you can apply safely CSS3 styles.

In your Moodle installation go to Plugins / Web services / Mobile and enter in the mobilecssurl field a valid URL pointing to a CSS file containing your custom styles (theme).

The CSS should be placed inside your Moodle installation (in your custom theme or inside a local plugin)

Once the user is logged in the app, there is a periodical process that retrieves your remote CSS files for applying your custom styles into the app.

Notice that on the first time a user opens the app, he will see the default "orange" style. Your custom styles will be applied once the user has added a site in the app.

Notice also that styles comes from a site, there is no way for changing the initial Add site / Manage account pages styles.

See [[Moodle Mobile Themes]] for additional information.
== Remote add-ons ==
Remote add-ons are available since Moodle 3.1 and Moodle Mobile 3.1.

A Moodle Mobile remote add-on is the mobile app version of a Moodle plugin that will be loaded when a user accesses the site on the app.

Moodle Mobile remote add-ons are stored within a Moodle plugin and are downloaded and lazy-loaded by the Mobile app in every site that uses them.

Remote add-ons are the best choice if you just want to support a Moodle plugin in the Mobile app without having to create and maintain a custom version.

See [[Moodle Mobile Remote add-ons]] for complete information.
== Creating a custom application ==
See [[Moodle Mobile custom apps]] or [https://moodle.com/mobileapp/ The Branded Moodle Mobile App service] by Moodle HQ
=== Building ===
There are two options for building the app, aka compile it to different devices:

'''Phonegap Build'''

Phonegap Build is an online service that lets you build the app automatically for different platforms. The main advantage is that it simplifies a lot the process of building.

You just put your www/ folder in a github account and Phonegaps automatically builds the app for different platforms pulling your github code.

Notice that the free version is for open repositories, but you can use the non-free version for private repositories.

In order to build your app using Phonegap Build you need to place a special config.xml file into the www/ folder, see the config.xml file for Moodle Mobile 2 (Please, note that this file is different from the one created by Ionic in the app root folder). Please follow the tutorial mentioned in [[Moodle Mobile custom apps]] to view all the steps required for building the app using Phonegap Build service.

'''Ionic CLI'''

You can also build the app using the Ionic CLI tools, see: http://ionicframework.com/docs/cli/run.html
== Configuring how the app should work via Moodle site settings ==
The app can be configured via Moodle site settingss. You can disable features, rename strings, add new elements to the main menu or change how log out works in the app. This requires Moodle 3.3 or the [[https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin]].

Please refer to the Configuring the app from your site section in this page: https://docs.moodle.org/en/Moodle_Mobile_guide_for_admins
== Testing and developing ==
=== Chromium or Google Chrome browser ===
See [[Moodle Mobile development using Chrome or Chromium]]
== Moodle Desktop ==
Refer to [[Moodle Desktop]]
== See also ==
[https://moodle.com/mobileapp/ Branded Moodle Mobile app service by Moodle HQ]

Moodle Mobile custom apps

2022-04-07T12:52:20Z

Pferre22:

{{Moodle Mobile 2 (Ionic 1)}}
== Overview ==
You will need a custom app if you want:
* Force the users to log in to your site URL
* Custom corporate image (name, app icon, theme, store entry)
* Add additional features or static pages
* Remove or change existing features
* Custom translation of the app
* Use your own notifications infrastructure
== Requirements ==
* Code editor (Sublime, WebStorm, Eclipse, Netbeans...)
* Github account (http://github.com/)
* Github desktop app (http://windows.github.com/)
* PhonegapBuild account
* Chromium browser as described here: [[Moodle Mobile development using Chrome or Chromium]]
== Steps for creating your Custom App ==
=== Setting up your computer ===
Follow these guides:
* [[Setting up your development environment for Moodle Mobile 2]]
* [[Moodle Mobile development using Chrome or Chromium]]
=== Fork the app ===
Use the Fork tool in:
https://github.com/moodlehq/moodleapp (You must be logged with your Github user!)

[[File:forkCustomApp.png]]
=== Clone the repo in your desktop ===
You can use your favourite GIT client (or GitHub Desktop clients)

[[File:clone.png]]
=== Create a new branch ===
Having the code in a separate branch in the forked repository will make very easy to maintain our customizations using git tools (merge, rebase)

[[File:branch.png]]
=== Edit the app settings file ===
'''/config.xml'''
* Change the widget id value (instead com.moodle.moodlemobile your own id)
* Change the app name and description
'''/www/config.json'''
* Change versionname
* Add a pre-fixed URL: Adding a field like “siteurl”: “http://mysite.abc”
* Change gcmpn (if you are using your custom Google Push infrastructure)
* Change the appid (required for making Push notifications work)
* Remove demo sites (“demo_sites”: “”)
=== Edit another app files ===
'''/www/core/component/settings/lang/x.json (x means all the languages)'''
* Change the “appname” string to match your custom app name (Not necessary in latest version Moodle Mobile 3.1.3), you can change it in config.json
'''/www/errorreport.js'''
* Change: var reportUrl to point to your custom error reporting system (if you want to use your custom one)
* Same for appVersion
=== Replace the app icons, splashscreen ===
* Replace the resources/ icon.png and splash images
* Replace also the www/img/moodle.png with an image matching your logo
* '''In a console:'''
** cd mycustomappdir/
** ionic resources
This will create your custom icon and splash images in all the required sizes

More information about Ionic’s image generation: http://ionicframework.com/docs/cli/icon-splashscreen.html
=== Add your custom styles ===
* Add your custom styles in scss/app.scss
* Sample theme available at: [[Moodle Mobile Themes]]
[[File:addCustomStyle.png]]
== Building your Custom App ==
There are two options for building the app:
* Ionic CLI
** Local building (require installation of Android and iOs SDK and emulators)
** See http://ionicframework.com/docs/cli/run.html
* Phonegap Build
** Remote building (cloud service)
** This is the recommended way because it doesn’t require to install all the SDK, emulators (or having to buy a Mac for developing)
=== Building with Phonegap Build ===
==== GitHub ====
* First of all, you need to create a new repository in GitHub. This is because Phonegap Build requires a different directory structure than Ionic CLI and we need a branch per platform.
* In your forked repository, run ''gulp'' so the build files are updated.
* Copy all the code inside the www/ in your forked repository directory to this new repo/branch.
* Also copy the /resources directory from the ionic project to a new /resources directory in the phonegap build repository
* You also have to place the /resources/icon.png and /resources/splash.png you used to create your resource files in the root folder in the phonegap build repository
* Use this repository as an example: <s>github.com/moodlehq/moodlemobile-phonegapbuild/tree/learn-moodle</s>
* In the Phonegap Build repo root folder you need to add a special config.xml file (different to the Ionic one), use [https://raw.githubusercontent.com/moodlehq/moodlemobile-phonegapbuild/learn-moodle/config.xml this file] as a template. Please, replace there the app name, versions, etc.
* Then, in the Phonegap build repo you need two create two additional branches based on master: android and ios
* In the android and ios branch you need to apply these changes:
Disable debugging in the app:

[[file:disableDebug.png]]

Add android or ios base class (so the app use native style widgets):

[[file:addBaseClass.png]]
* The rest of the commits can be safely omitted:
** Add reporting library
** Add official tag
==== Phonegap ====
* Create an account in ''PhoneGap''.
* For iOS you need to create certificates/provisioning files.
* For Android, you can download and install the .apk for testing, for production follow the previous guide.
* In order to build, add your repository https link and also the branch in the Phonegap Build settings (you will have to do two different builds: one for the android branch and another one for the ios branch)
* In order to update your app for phonegap build you have to (this will apply all the specific android/ios commits to your master branch):
** Upload new versions of the app to the www/ directory and then execute the commands:
** git rebase master android
** git push -f
** git rebase master ios
** git push -f
=== Remove existing features ===
* You can only remove add-ons.
* In order to disable an add-on you need to delete the folder.
* Add-ons are located in the www/addons folder.
* In case you want to remove a particular functionality of an add-on you will need to edit the files inside the addon. Please notice that removing a state is not enough for a feature to be disabled, you also need to remove all the links to that state to prevent errors.
* Then run gulp or ionic serve in the project root folder so the build files are created.
=== Change the app strings ===
* Language strings are located in:
** www/core/lang folder (a different file for each language)
** www/core/components/COMPONENT_NAME/lang folder
** www/addons/ADDON_NAME/lang folder
* Language files are .json files, you can edit it using a text editor. Please, use jsonlint.com to validate that the new language file is correct.
* Then run '''gulp''' or '''ionic serve''' in the project root folder so the build files are created
=== Change the initial screen (add site) ===
* To make the app use a fixed site URL you need to add a new setting in the config.json file: “siteurl”: “http://yourmoodle.com”
* Then run '''gulp''' or '''ionic serve''' in the project root folder so the build files are created.
You can see an example from our Learn Moodle app (that is a custom version of Moodle Mobile) here: https://github.com/jleyva/moodleapp/blob/learn-moodle/www/config.json
=== Keep your custom version up2date ===
* Sync your fork: https://help.github.com/articles/syncing-a-fork/
* Rebase your changes (and resolve conflicts):
** git rebase master yourcustombranch
* Upgrade your version number
* Commit your changes
* Apply the changes in your Phonegap Build specific repository
* Rebuild with Phonegap build for both android and ios branches
* Publish in the store

Moodle Mobile Building the app for Android

2022-04-07T12:50:28Z

Pferre22:

{{Moodle App (Ionic 3)}}
Remember that you can also build the app using an external system called Phonegap Build, see [[Moodle_Mobile_Customization#Building]]
{{obsolete}}

== Installing the Android SDK ==
Building the app for Android is easy once you have successfully installed all the required software.

Since we are using Phonegap as framework for creating the app, the documentation you have to follow is just in this link plus additional steps for installing plugins:
<s>docs.phonegap.com/en/guide_getting-started_android_index.md.html#Getting%20Started%20with%20Android</s>

Notice the following:
* You must read carefully the document and not use white spaces in some names and ids. (It's adviced in the document)
* You can optionally not use Eclipse and instead use adb command line or cordova script tools
* In the "4. Setup New Project" The package_name is the app id that your app will have in the Android Market (Play Store), so it must be unique. If you are going to develop for the official app you have to use com.moodle.moodlemobile, if you are going to develop a custom app, you will have to add your own unique id.
* If you want to connect a Device to your Eclipse and you are using Windows, you must install the Android USB Drivers, see http://developer.android.com/tools/extras/oem-usb.html#InstallingDriver
== Add the Mobile app HTML5 files ==
Go to your project folder, assets/www and add just there all the files from https://github.com/moodlehq/moodlemobile
== Installing additional Phonegap plugins ==
The Android app requires two additional Phonegap plugins to be installed:
=== WebIntent ===
For opening files according their mime type: https://github.com/phonegap/phonegap-plugins/tree/DEPRECATED/Android/WebIntent

For installing the plugin follow this instructions: https://github.com/phonegap/phonegap-plugins/blob/DEPRECATED/Android/WebIntent/README.md#adding-the-plugin-to-your-project
== Build, compile, test your app ==
We suggest you to use Eclipse tools for testing, deploying the app

In any case, you can always use the Cordova command line tools.

The cli tools are in your project folder, directory cordova
== Signing your app ==
''The Android system requires that all installed applications be digitally signed with a certificate whose private key is held by the application's developer. The Android system uses the certificate as a means of identifying the author of an application and establishing trust relationships between applications. The certificate is not used to control which applications the user can install. The certificate does not need to be signed by a certificate authority: it is perfectly allowable, and typical, for Android applications to use self-signed certificates.'' See: http://developer.android.com/tools/publishing/app-signing.html

And also for Eclipse: http://developer.android.com/tools/publishing/app-signing.html#ExportWizard
== Uploading your custom app to the Google Play Store ==

== Build the official Moodle Mobile app on a Mac ==
# Install SDK
#*http://developer.android.com/sdk/index.html#download - it will install Eclipse / ADT plugin / Android SDK
# Add the SDK tools/platform-tools folders to your PATH
# Install NodeJs
#*http://nodejs.org/
# Install cordova-cli
#* ''sudo npm install -g cordova'' - it will install cordova. Note that on my machine I have some warnings about the android bootstrap process being skipped but all the following steps seem to work ok anyway...
# Create a Android project
#*''/usr/local/lib/node_modules/cordova/bin/cordova create ~/Apps/moodlemobile_android_cordova com.moodle.moodlemobile MoodleMobileBeta''
#* ''cd ~/Apps/moodlemobile_android_cordova''
#* ''sudo /usr/local/lib/node_modules/cordova/bin/cordova platform add android''
#* ''sudo /usr/local/lib/node_modules/cordova/bin/cordova build'' - not necessary, just check the build works.
# In Finder change the permission on ~/Apps/moodlemobile_android_cordova folder: Read + Write to everyone
# Open eclipse, add a new Android project from existing source pointing to /Users/jerome/Apps/moodlemobile_android_cordova/platforms/android. Test you can build the default Cordova app on your phone.
# Copy the Moodle mobile app into assests/www folder
#* ''git clone git://github.com/moodlehq/moodlemobile.git ./moodlemobile''
#* ''mv platforms/android/assets/www/ platforms/android/assets/www_old/''
#* ''mv ./moodlemobile/ platforms/android/assets/www/''
#* ''cp platforms/android/assets/www_old/cordova.js platforms/android/assets/www/''
# Add the cordova plugins
#* ''git clone git://github.com/alunny/ChildBrowser.git ./ChildBrowser'' - we are now going to install cordova compatible plugin with the plugin install command line.
#* ''sudo /usr/local/lib/node_modules/cordova/bin/cordova plugin add ChildBrowser/''
# Add manually phonegap plugins
#* ''git clone git://github.com/phonegap/phonegap-plugins.git ./phonegap-plugins''
#* ''cp phonegap-plugins/Android/WebIntent/webintent.js platforms/android/assets/www/''
#* ''mkdir platforms/android/src/com/borismus''
#* ''mkdir platforms/android/src/com/borismus/webintent''
#* ''cp phonegap-plugins/Android/WebIntent/WebIntent.java platforms/android/src/com/borismus/webintent''
#* In Eclipse, add a package to src folder. The value should be com.borismus.webintent
#* In your res/xml/config.xml file, add ''<plugin name="WebIntent" value="com.borismus.webintent.WebIntent" />'' where you define the plugins.
# copy the icons
#* ''cp platforms/android/assets/www/img/icon/android/icon-36-ldpi.png platforms/android/res/drawable-ldpi/icon.png''
#* ''cp platforms/android/assets/www/img/icon/android/icon-48-mdpi.png platforms/android/res/drawable-mdpi/icon.png''
#* ''cp platforms/android/assets/www/img/icon/android/icon-72-hdpi.png platforms/android/res/drawable-hdpi/icon.png''
#* ''cp platforms/android/assets/www/img/icon/android/icon-96-xhdpi.png platforms/android/res/drawable-xhdpi/icon.png''
# Edit the AndroidManifest.xml
#* increment ''android:versionCode="359" android:versionName="1.2.0.2"''
#* keep the following permissions: ''INTERNET, RECORD_AUDIO, RECORD_VIDEO, READ_CONTACTS, WRITE_CONTACTS, WRITE_EXTERNAL_STORAGE, ACCESS_NETWORK_STATE''
#* ''android:debuggable="false"'' - this reduce the apk size file from 7M to less than 1M!
# Edit ''res/values/strings.xml'' and change the app name for "Moodle mobile" - this app name appears on your Android phone dashboard. The Google Play Store app name comes from the Google Play publisher console.
# Clean up the app to reduce apk file size
#* ''rm -rf platforms/android/assets/www_old/''
#* ''rm -rf platforms/android/assets/www/img/splash''
#* ''rm -rf platforms/android/assets/www/img/icon''
# In Eclispe, build and test the app.
# In Eclipse, File > Export the app with the Moodle HQ Google Play keystore. Then upload the APK to Google Play.
=== Warnings ===
* if you previously installed a different platform then you'll get an error when adding the cordova plugin. It's advised to install both platforms at the same time. Then add the cordova plugin(s), then copy the app content into www. Don't forget cordova.js and plugin js/files. Then you can manually install phonegap plugins.
= See also =
* [[Moodle Mobile Building the app for iOS]]
* [[Moodle Mobile]]

Moodle Mobile Testing with Phonegap Developer app

2022-04-07T12:47:29Z

Pferre22: Remove legacy links

{{Moodle Mobile 1}}
''Phonegap Build'' service was discontinued October, 1 2020.
The ''Phonegap Developer app'' is a tool that allow developing locally and see the changes instantly on your mobile device.

It's not a tool that can be used for developing and testing all the features of the Moodle Mobile app since it doesn't support all the plugins used by the app and also, the FileTransfer plugin are not fully supported.

It doesn't support also connection to different sites using XHR (Ajax) request using POST or HEAD methods.

The app is suitable for testing mainly CSS / Design issues in different devices (iOs, Android and WindowsPhone 8)

If you want to test the Moodle Mobile app in order to polish design issues, please follow this instructions:
* Install the Phonegap Developer app in your iOs, Android or WindowsPhone 8 device
* Install node.js http://nodejs.org/
* In a terminal/console: sudo npm install -g phonegap
* Terminal/console: cd directory_where_to_create_the_project
* Terminal/console: phonegap create moodlemobile
* Terminal/console: cd moodlemobile
* Delete the contents of the www/ folder
* Copy the Moodle Mobile app files into the www/ folder
* In a terminal, cd to the project folder and then: phonegap serve (This will launch a local server, you can stop the server doing a ctrl+c)
* Open the app in a device, and copy the server Address that the previous command displayed
* In the Moodle Mobile app Site URL field enter: mmtest (It's a "fake" test site, remember that you can't connect to real sites using the Phonegap Developer app)
Remember that every time you want to use the Phonegap Developer app, you need to open a terminal/console, cd to your phonegap project folder, and run the command:
phonegap serve
If you have problems testing with the app, try to close the app in your Mobile device and stop the Phonegap server (ctrl + c in the terminal)
[[Category: Mobile]]