Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Moodle Mobile 2 (Ionic 1) Remote add-ons: Difference between revisions

From MoodleDocs
No edit summary
(13 intermediate revisions by 4 users not shown)
Line 12: Line 12:
* Mobile remote add-ons are placed inside Moodle plugins (outside the Mobile app).
* 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 language files must include the whole component prefix.
* Mobile remote add-ons uses special placeholders for paths inside CSS files or Javascript code.
* Mobile remote add-ons uses special placeholders for paths inside Javascript code.


== How to create a remote add-on ==
== How to create a remote add-on ==
Line 29: Line 29:
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.
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/markn86/moodle-mod_certificate/blob/MOODLE_31_STABLE/classes/external.php
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 service using the "services" field when declaring external functions, see: https://github.com/markn86/moodle-mod_certificate/blob/MOODLE_31_STABLE/db/services.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.
Remember that this is only available from Moodle 3.1 onwards.
Line 38: Line 38:


Refer to [[Moodle Mobile Plugins Development]]
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 ===
=== 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:
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:
Line 46: Line 74:
* In this ''addon.js'', replace the paths to your addon folder with ''$ADDONPATH$''. For example, if you have
* 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>templateUrl: 'addons/myaddon/templates/index.html'</nowiki>
...
<nowiki>$scope.icon = 'addons/myaddon/icon.gif';</nowiki>
you should set it like this:
you should set it like this:
  <nowiki>templateUrl: '$ADDONPATH$/templates/index.html'</nowiki>
  <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:
* Add your addon's prefix to language strings. That is, if you have a string like this:
  <nowiki>"getcertificate": "Get your certificate"</nowiki>
  <nowiki>"getcertificate": "Get your certificate"</nowiki>
Line 53: Line 85:
  <nowiki>"mma.mod_certificate.getcertificate": "Get your certificate".</nowiki>
  <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 important that language files are inside a "''lang''" folder in your addon's root folder.
* 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.
* 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.
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 ===
=== Remote add-on publishing ===
Line 62: Line 97:


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

Revision as of 16:02, 9 May 2017

Moodle 3.1

Only available for Moodle 3.1 onwards.

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.

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 (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 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 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
templateUrl: 'addons/myaddon/templates/index.html'
...
$scope.icon = 'addons/myaddon/icon.gif';

you should set it like this:

templateUrl: '$ADDONPATH$/templates/index.html'
...
$scope.icon = '$ADDONPATH$/icon.gif';
  • Add your addon's prefix to language strings. That is, if you have a string like this:
"getcertificate": "Get your certificate"

you need to set it like this:

"mma.mod_certificate.getcertificate": "Get your certificate".

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

See also