Moodle App Plugins Development Guide

Context

Since Moodle 3.1 it is possible to support different types of Moodle plugins in the Mobile app via the Remote add-ons functionality.

Remote add-ons allow a developer to add complete support to their plugins in the Mobile app, but they have some disadvantages:

Remote add-ons are not easy to develop and test since they are required to be developed as an Angular JS/Ionic module.
A zip file containing the plugin must be downloaded from the server to be lazy-loaded.
It is not easy to maintain or upgrade them.
Developers had to set up a local Mobile development environment

In order to allow plugin developers to make their plugins compatible with the app, the Mobile team has been thinking in a new way to extend the mobile app features following these premises:

It has to be easy to develop
It should work without developing Angular/Ionic code
It has to be easy to maintain
It has to be supported since Moodle 3.1 at least
Should support all the different types of Moodle plugins supported by the app
Should work in any type of device
Should not require JavaScript at all, although in some cases it will be needed. In the latter case, we’ll try to simplify the required JavaScript

New approach

We published an initial draft specification, and last month we started its implementation. During the implementation process we decided to make the following changes to the initial plans in order to make developers life easier:

There will be just one way to support plugins in the app.
This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
The use of JavaScript will be optional (but some type of advanced plugins may require it)
Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them.

Important notes:

Moodle Mobile 3.5 (to be released May 2018) will be the first version of the Mobile app supporting this new type of plugins.
Remote add-ons will have to be migrated to the new simpler way (following this documentation)
These features will be natively supported in Moodle 3.5, but for previous versions you will need to install the Moodle Mobile Additional Features plugin.

How it works

The overall idea is to allow Moodle plugins to extend different areas in the app with just PHP server side code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:

Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use Ionic components so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
Those functions will be exported via the Web Service function tool_mobile_get_content
As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

Step by step example

In this example, we are going to update an existing plugin (Certificate activity module) that currently uses a Remote add-on. This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (see last commit) https://github.com/jleyva/moodle-mod_certificate/commits/MOBILE-2363

Step 1. Update the db/mobile.php file

In this case, we are updating an existing file but for new plugins, you should create this new file.

$addons = array(

   "mod_certificate" => array( // Plugin identifier
   	'handlers' => array( // Different places where the plugin will display content.
           'coursecertificate' => array( // Handler unique name (alphanumeric).
           	'displaydata' => array(
               	'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' => array(

'mobile_course_view' => array(),
'mobile_issues_view' => array()
) // Function that needs to be downloaded for offline.

           )
   	),

	'lang' => array(	// Language strings that are used in all the handlers.

               array('pluginname', 'certificate),
               array('summaryofattempts', 'certificate),
               array('getcertificate', 'certificate),
               array('requiredtimenotmet', 'certificate),

		 array('viewcertificateviews', 'certificate')

       ),
   )

);

Plugin identifier: A unique name for the plugin, it can be anything (there’s no need to match the module name).

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

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

Delegate: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

Method: This is the function in the Moodle component/lib.php file to be executed the first time the user clicks in the new option displayed in the app. The function should be a method of a Mobile class under the output/mobile namespace.

Offlinefunctions: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.; In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.; Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).; You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid); Prefetching the module will also download all the files returned by the methods in these offline functions (in the files array).

Lang: The language pack string ids used in the plugin by all the handlers. Please note that you should avoid adding all the plugin string ids (including those unused) because the Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

Documentation