Moodle Mobile 2 (Ionic 1) Plugins Development
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 Customization) before you start developing!
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
var templates = [
"root/lib/text!root/plugins/participants/participants.html",
"root/lib/text!root/plugins/participants/participant.html"
];
define(templates,function (participantsTpl, participantTpl) {
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
settings: {
name: "participants",
type: "course",
menuURL: "#participants/",
lang: {
component: "moodle"
}
},
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:
settings: {
name: "mycustomplugin",
type: "general",
menuURL: "#custom/",
lang: {
component: "local_mycustomplugin",
strings: {
"stringid1": "string contents",
"stringid2": "string contents 2"
}
}
},
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
storage: {
participant: {type: "model"},
participants: {type: "collection", model: "participant"}
},
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
routes: [
["participants/:courseId", "participants", "showParticipants"],
["participant/:courseId/:userId", "participants", "showParticipant"],
],
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
sync: {
handler: MM.plugins.myplugin.functionName,
time: 60
},
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
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);
});
},
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
templates: {
"participant": {
model: "participant",
html: participantTpl
},
"participants": {
html: participantsTpl
}
}
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
MM.registerPlugin(plugin);
With this single line we register the plugin in the global Namespace MM (the main library of the app)
Uses 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
MM.log = function(info) {
// Here goes the code for my custom log function that overrides the default functionality
}
MM.registerPlugin(plugin);
Load a custom CSS stylesheet
$('head').append('<link rel="stylesheet" href="plugins/myplugin/mycss.css" type="text/css" />');
MM.registerPlugin(plugin);
Change the main layout of the app
In this case we change the Add Site screen.
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);
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:
var notificationsFilter = MM.db.where("notifications", {siteid: MM.config.current_site.id});
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:
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});
});
Internationalization functions
Getting a translated string
MM.lang.s("string_id");
Sample code:
MM.lang.s("therearenotnotificationsyet");
Templating functions
Render a template
MM.tpl.render(html, elements);
Sample code:
var tpl = {users: users, deviceType: MM.deviceType, courseId: courseId};
var html = MM.tpl.render(MM.plugins.participants.templates.participants.html, tpl);
Template:
<section class="users-index-list">
<form class="search">
<input type="search" results="5" placeholder="Search...">
</form>
</section>
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 Developing a plugin tutorial
See also
JsDoc Reference http://moodlehq.github.com/moodlemobile/