|
|
| Line 1: |
Line 1: |
| {{obsolete}}
| |
| {{Moodle Mobile}} | | {{Moodle Mobile}} |
| === Overview ===
| |
|
| |
|
| Plugins allow developers to extend the app functionalities.
| | == Overview == |
| 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).
| | 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! | | IMPORTANT: Read carefully this document ([[Moodle Mobile 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]
| | == Moodle Mobile 2 addons == |
| | |
| === 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====
| |
| | |
| <code javascript>
| |
| var templates = [
| |
| "root/lib/text!root/plugins/participants/participants.html",
| |
| "root/lib/text!root/plugins/participants/participant.html"
| |
| ];
| |
| | |
| define(templates,function (participantsTpl, participantTpl) {
| |
| </code>
| |
| | |
| 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====
| |
| | |
| <code javascript>
| |
| settings: {
| |
| name: "participants",
| |
| type: "course",
| |
| menuURL: "#participants/",
| |
| lang: {
| |
| component: "moodle"
| |
| }
| |
| },
| |
| </code>
| |
| | |
| 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:
| |
| | |
| <code javascript>
| |
| settings: {
| |
| name: "mycustomplugin",
| |
| type: "general",
| |
| menuURL: "#custom/",
| |
| lang: {
| |
| component: "local_mycustomplugin",
| |
| strings: {
| |
| "stringid1": "string contents",
| |
| "stringid2": "string contents 2"
| |
| }
| |
| }
| |
| },
| |
| </code>
| |
| | |
| 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====
| |
| <code javascript>
| |
| storage: {
| |
| participant: {type: "model"},
| |
| participants: {type: "collection", model: "participant"}
| |
| },
| |
| </code>
| |
| | |
| 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====
| |
| <code javascript>
| |
| routes: [
| |
| ["participants/:courseId", "participants", "showParticipants"],
| |
| ["participant/:courseId/:userId", "participants", "showParticipant"],
| |
| ],
| |
| </code>
| |
| | |
| 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'''
| |
| <code javascript>
| |
| sync: {
| |
| handler: MM.plugins.myplugin.functionName,
| |
| time: 60
| |
| },
| |
| </code>
| |
| | |
| 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====
| |
| <code 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);
| |
| });
| |
| },
| |
| | |
| </code>
| |
| | |
| 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====
| |
| <code javascript>
| |
| templates: {
| |
| "participant": {
| |
| model: "participant",
| |
| html: participantTpl
| |
| },
| |
| "participants": {
| |
| html: participantsTpl
| |
| }
| |
| }
| |
| </code>
| |
| | |
| 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====
| |
| <code javascript>
| |
| MM.registerPlugin(plugin);
| |
| </code>
| |
| | |
| 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
| |
| | |
| <code javascript>
| |
|
| |
| MM.log = function(info) {
| |
| // Here goes the code for my custom log function that overrides the default functionality
| |
| }
| |
| | |
| MM.registerPlugin(plugin);
| |
| </code>
| |
| | |
| === Load a custom CSS stylesheet ===
| |
| | |
| <code javascript>
| |
|
| |
| $('head').append('<link rel="stylesheet" href="plugins/myplugin/mycss.css" type="text/css" />');
| |
| | |
| MM.registerPlugin(plugin);
| |
| </code>
| |
| | |
| | |
| === Change the main layout of the app ===
| |
| | |
| In this case we change the Add Site screen.
| |
| | |
| <code 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);
| |
| </code>
| |
| | |
| | |
| === Load extra base languages ===
| |
| | |
| <code 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);
| |
| </code>
| |
| | |
| 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:
| |
| | |
| <code javascript>
| |
| var notificationsFilter = MM.db.where("notifications", {siteid: MM.config.current_site.id});
| |
| </code>
| |
| | |
| ====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:
| |
| | |
| <code 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});
| |
| });
| |
| </code>
| |
| | |
| === Internationalization functions ===
| |
| | |
| ====Getting a translated string====
| |
| | |
| MM.lang.s("string_id");
| |
| | |
| Sample code:
| |
| | |
| <code javascript>
| |
| MM.lang.s("therearenotnotificationsyet");
| |
| </code>
| |
| | |
| === Templating functions ===
| |
| | |
| ====Render a template====
| |
| | |
| MM.tpl.render(html, elements);
| |
| | |
| Sample code:
| |
| | |
| <code javascript>
| |
| var tpl = {users: users, deviceType: MM.deviceType, courseId: courseId};
| |
| var html = MM.tpl.render(MM.plugins.participants.templates.participants.html, tpl);
| |
| </code>
| |
| | |
| Template:
| |
| | |
| <code 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>
| |
| </code>
| |
| | |
| === Message popups/dialogs===
| |
| | |
| MM.popMessage(text, options);
| |
| | |
| MM.popErrorMessage(text, options);
| |
|
| |
|
| === Device ===
| | Moodle |
|
| |
|
| MM.deviceType (returns phone or tablet) | | 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). |
|
| |
|
| MM.deviceConnected() (returns true or false if the device has Internet access)
| | 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. |
|
| |
|
| For a tutorial about developing plugins for Moodle Mobile see: [[Moodle Mobile Developing a plugin tutorial]]
| | 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. |
|
| |
|
| == See also ==
| | The delegates we have are: |
| | * $mmSideMenuDelegate: The addons registered in here will be shown in the app’s side menu. |
| | * $mmCourseDelegate: The addons registered in here will be shown under each course in the course list. |
| | * $mmUserDelegate: The addons registered in here will be shown in a user page. |
| | * $mmSettingsDelegate: The addons registered in here will be shown in the preferences page. |
|
| |
|
| [http://es.slideshare.net/juanleyva/creating-a-custom-moodle-mobile-app-moodle-moot-spain-2014 Creating a custom Moodle Mobile app - MoodleMoot Spain 2014]
| | === Structure of an addon === |
| JsDoc Reference http://moodlehq.github.com/moodlemobile/
| |
